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Provider for the Macintosh community. 
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"Without a doubly the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools. ** 

- MacUser Magazine Eddy Awards 

“A distinct improvement over Apple's ResEdil. ” 

- MacTech Magazine 

^Every Mac OS developer should own a copy of Resorcerer . * 

- Leonard Rose n t hoi ; Aladdin Systems 

(t Without Resorcerer, our localization efforts would look like a 
Tower of Babel. Do n V do p rod net w i tho ut it ! M 

- Greg Gala nos, CEO and President, Metro works 


“ Resorcerer's data template system is amazingG 

- Bill Goodman, author of Smaller Installer and Compact Pro 

“Resorcerer Rocks! Buy it, you will NOT regret it.™ 

- Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many tim es over in saved time and effort * 

- MacUser review 

“The template that disassembles PICTs is a wesome!” 

— Bill Steinberg, author of Pyro! and PBTools 

“Resorcerer proved indispensable in its own creation!” 

- Doug McKenna r author of Resorcerer 
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(Educational, quantity, or 
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Includes; Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, PO's, or Visa/MC 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Red, 
International Shipping 
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PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
resorcerer@mathemaesthetics.com 
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* Very fast, HFS browser for viewing file tree of all volumes 

■ Extensibility for new Res ore crer Apprentices (CFM plug-ins) 

* New AppleScript Dictionary Oaete’) Apprentice Editor 

* MacOS 8 Appearance Manager-savvy Control Editor 

■ Power Plant text traits and menu command support 

* Complete AIFF sound file disassembly template 

* Big-, little-, and even mixed-endian template parsing 

* Auto-backup during file saves; folder attribute editing 

* Ships with PowerPC native, fat, and 68K versions 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-hased, not disk-fi le-based, design and operation 
All file information and common commands in one easy-lo-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rezdike scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, detb’s, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


To order by credit card, or to get the latest news, bugfixes, updates, and apprentices, visit our website... 

www.mathemaesthetics.com 
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VIEWPOINT 


By William Porter, POLTIPOPE, Houston, Texas 


4D/WebSTAR Summit 2000 


An exclusive MacTech report 


The 4D/WebSTAR Summit was held October 4 —8 in 
San Diego, California. The weather in San Diego was 
uncharacteristically gloomy throughout the Summit, 
but inside the ITS, Grant Hotel, the atmosphere was 
sunny and warm. 

This was the largest gathering of 4D developers 
ever. According to Mike Erickson of Automated 
Solutions Group, co-sponsor with 41), Inc. of this year s 
Summit, there were almost 450 developers in 
attendance, from two dozen countries. A dozen third- 
party vendors displayed their products or services 
during the Summit. The three-day program consisted of 
over 70 sessions. Some of these were presented by 
personnel from 4D, Inc. or WebSTAR and a lew were 
given by third-party vendors who discussed their 
products, BuL most were presented by the several dozen 
independent developers who ensured that the program 
was grounded not in marketing but in practical problem 
solving. Best of all, there were more new users than 
ever before. There was a special track for 4D beginners 
and a free one-day seminar taught by Liz Delgado 
designed to bring newbies rapidly up-to-speed. 

4D, Inc., president and CEO Brendan Covency, in 
his keynote address, reported that the state of the 
company was good indeed. NASA recently purchased 
an agency-wide site license for 4D. Projected revenues 
for fiscal year 2000 come to $28 million, with operating 
costs of only $6 million. Revenues have grown 80% in 
the last two years. Increased expenditures on 
marketing are paying off: 4D, the oldest RDBMS for the 
Mac, is once again a visible and respected presence in 
the world of Mac OS database development. 

Webstar 

The acquisition of Starnine, makers of WebSTAR, in 
March 2000, overnight made 4D, Inc. a major web 
player. If you weren’t paying attention at the time, 
WebSTAR is the software that the U.S. Army moved its 


web site to a year ago, after it dumped Microsoft IIS 
because of its weak security. Exactly how WebSTAR 
will play into 4D's long-term product struLegy remains 
to be seen. While 4D already has outstanding 
proprietary tools for web-serving databases, it seems 
reasonable to expect closer integration between 4D, 
Inc/s database anti web-server products in the future. 
Bui CJ. Holmes, formerly of Star nine and now 4D, 
Inc/s director of engineering for WebSTAR, assured me 
that WebSTAR is not going to be absorbed into 4D as a 
component, or vice versa. And in an exclusive 
interview with MacTECH, Brendan Covency confirmed 
this, saying that 4D, Inc. remains an 'open-systems 
company” and that WebSTAR will continue to work 
well with all databases on the Mac. This will be good 
news for FileMaker Pro developers using Lasso or the 
FileMaker Web Companion and for users of other back 
ends like Valentina or Prime Base, 

No release date was given, but attendees were 
given some hints about what to look for in WebSTAR 5. 
It was described as a well-behaved application with an 
instinct for self-preservation; if a child process dies for 
any reason, the parent process will start a new process 
automatically. WebSTAR 5 will ship with a bunch of 
new features, including support for Perl; support for 
multiple processors; more plug-ins and services such as 
calendars, forms processing, etc. Tests run with 
WebBench show spectacular improvements in speed; 
WebSTAR 4,x runs around 50 connections per second, 
WebSTAR 5 has been tested at over 420 connections a 
second or 37 million connections a day. These are 
some serious web-serving numbers. Finally, they have 
WebSTAR 5’s core features running under OS X already 
as a BSD application. 

In honor of the company’s new product, there was 
a special track devoted to WebSTAR and other issues of 
interest to web administrators; about 50 attendees 
registered for that track specifically. One web 

Continued on page 96 
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Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer: It's both! 

MacHASP USB is the world's first 
software protection key for the 
iMac. It gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big selling 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Plus you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

"For atl USB-equipped Macs running an OS 
with USB support. Fully compatible with the 
AOB version of MacHASP. 
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212-564-5678 
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KNOWLEDGE SYSTEMS LTD 


Mac software protection provider, Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 


GETTING 
STARTED — 
NETWORKING 


By John C. Welch 


Networks 201 pt. 5 


Layer 3 ; The Network Layer 


Refresh 

From the first article in our series, 
we recall that Layer 3, the Network 
Layer* is responsible for handling 
network connections that exist past the 
next object in line. In other words. Layer 
3 is the routing layer. This is the layer 
that handles packet transmission over 
subnets, and between different types of 
networks. Layer 3 is not required in all 
circumstances. If you are using a 
network that does not route, or does not 
need routing information* Layer 3 may 
be very thin, or nonexistent. This is also 
the lowest level of the OSI model that 
communicates in an end-to-end fashion. 
This means that us far us Layer 3 is 
concerned, there are no Layers 1 or 2, 
only other machines running Layer 3 
protocols. This is what we will talk 
about this month, so into the Fray! 

Layer 3 

As we noted above, the Network 
Layer deals with a bigger scope than the 
Data Link Layer. Where the Data Link 
Layer is concerned with getting frames 
from wire end A to wire end B, the 
Network Layer is concerned with getting 
the packet from the source to the 
destination, regardless of how many 
wires, routers, or other points in 
between the source and the destination. 
Like all the other layers, the Network 
Layer provides services to the Layer 


above it, in this case, the Transport Layer. This interface 
between the two layers is often the boundary of the network 
subnet, or the boundary between the customer, (the 
Transport Layer and up), and the carrier, (Network Layer and 
down.) To do this, the Network Layer services v/ere designed 
with three primary goals; 

1) Network Layer services need to be independent of the 
subnet technology* That is. the services provided by the 
layer need to not care about whether the subnet is a 
TCP/IP, AppleTalk, or any other protocol. 

2) It needs to shield the Transport Layer from the number, 
type, and topology of the subnets present. The Transport 
Layer does not need to know any of this, as this is what 
the Network Layer does. All the Transport Layer needs to 
do is hand off information and data to the Network Layer, 
and let the Network Layer do it s job. This is in keeping 
with the general idea of each Layer having a specific 
purpose within the OSI model. 

3) The network addresses used by the Transport Layer 
should be part of a uniform numbering plan, regardless of 
the scope of the network. In other w r ords, the transport 
layer shouldn’t have to deal with how the network is 
addressed, or the scope of those addresses. Just that the 
addresses are there, and apply across the network* 

To accomplish these goals, there are tw F o points of view 
on how to do this, and both work well within their areas. The 
first point of view is that of the Internet community, and says 
that the only thing the subnet, and by extension, Layer 3 
should be doing is pushing and getting bits. This takes the 
argument that the subnet is inherently unreliable, and that 
any error control and flow control need to be handled by the 
endpoints, or hosts. The Network Layer here, should be 
connectionless, and use only the smallest amount of network 
primitive commands, (SEND PACKET, RECEIVE PACKET* and 


John Welch < jwelch@aer.com> is the Mac and PC Administrator for AER Inc„ a weather and atmospheric science company 
in Cambridge, Mass, He has over fifteen years of experience at making computers work. IIis specialties are figuring out ways 
to make the Mac do what nolxjdy thinks it can. and showing that the Mac is the superior administrative platform, 
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not much else,) The reason that the layer should do no flow 
or error control is because the hosts are going to do that 
anyway, and besides, who knows where the packets really 
go in between points A and B with any reliability. To support 
the multiple paths packets may be taking, each packet needs 
to carry the full addresses of the source and destination. 

In the other corner is the point of view of the 
telecommunications industry. This says that the subnet 
should be reliable, and should he connection oriented. There 
should be some error and flow control in the subnet, and all 
data transfers should have certain basic properties along the 
following lines: 

1) Before sending or receiving data, a connection is set up 
between the source and the destination. This connection 
creates a path between the two, and is a temporarily static 
path that encompasses any midpoint devices. This 
connection has a unique identifier that helps route packets, 

2) Once the connection is set up, then the two ends 
negotiate parameters, quality, cost, etc, 

3) All communications are bi-directional, and packets are 
delivered in sequence, 

4) Flow control is provided automatically to keep from 
overloading one or both ends. 

5) Once it is no longer needed, the connection is tom down, 
and all used buffers are flushed. 

The real difference between the connectionless and 
connection - oriented arguments is where the complexity of 
the layer is handled. In a connectionless protocol, the end 
points deal with all the complexities of the network. This is 
because computing power is cheap, and it is easier to 
upgrade end nodes than major intermediary devices. Also, 
some functions, such as real-time oriented applications are 
far more concerned with speed of delivery, rather than 
accuracy of delivery. The connection - oriented folks argue 
that the subnet should help provide reliable, trouble-free 
service, and the end nodes shouldn’t have to run complex 
Transport Layer protocols. In addition, there is a point to be 
made that real-time data does just as well in a reliable 
connection as in a connectionless service, and that it is easier 
to provide certain real-time information atop a reliable 
c on n e ct i on - o ri e n t e d protoco I, 

In the end, both are used, depending on the 
application’s needs. File transfers want a reliable connection, 
to avoid data corruption, whereas live video feeds prefer to 
drop a frame or two, while still keeping the stream running, 
without the overhead of resending multiple packets. 
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Connection — oriented services 

These work primarily by creating virtual circuits that act 
as temporary paths between two end nodes- The idea here is 
to avoid having to create, or even look for a new route for 
every packet that is transferred. Instead, when a connection 
is established, a route between the two end nodes is created 
and stored, to be used for all traffic for the duration of that 
connection. Once the connection is taken down, the virtual 
circuit is also terminated. This has the effect of requiring a lot 
more out of the intermediary devices on the subnet. Routers 
must maintain an entry for every virtual circuit that is using it. 
They must check every packet for the virtual circuit number, 
so they can determine where the packet goes next. 

When a new connection is created, the first unused 
virtual circuit, (VC) number is used. It is important to note 
that these numbers are of total significance, not global. This 
avoids having to synchronize every connection with every 
other connection to avoid VC number conflicts. Another issue 
with VC numbers is when a connection is initialed by both 
ends at once, This leads to two adjacent routers creating a 
duplex circuit that could have conflicting, (identical) VC 
numbers. At this point, the routers don't have any way to tel] 
which way the packet is moving. One of the ways this is 
avoided is in use simplex connections. 

The advantages to VCs are that the addressing is much 
simpler, relying on VC numbers more than full blown 
addresses. The routing ends up being similar, because once 
the connection is established, that is the route that all packets 
will take for the duration of the connection. VCs also help 
with bandwidth needs, because part of the connection process 
is quality negotiation, so if need be, bandwidth can be 
reserved by the connection before the first packet is moved. 

However, if ihe data needs of the connection are small, 
the overhead in setting up the VC can often be not worth the 
effort involved. Also, if one of the routers on the VC goes 
down, then the connection is broken, and has to be re¬ 
established. In fact, all the connections being serviced by 
that router are dropped, and have to be re-established. 

Connectionless services 

These are also known as datagram networks, as that is 
the name used for the packets in this type of network. Each 
datagram contains the complete addresses of its sender and 
recipient. There is no connection establishment, nor is there 
a route established for that da La either. Indeed each datagram 
can go a different way than the datagrams in front of or 
behind it. 

This has the advantage of being a more reliable method 
of data delivery if the subnet quality is unknown, or not 
reliable. Since each datagram Is independently routed, no 
one device can destroy the entire delivery. The downside to 
this is that since every datagram is independently routed, the 
routing becomes much more complicated than for a VC, This 
also makes congestion and flow control difficult. 


Routing 

We said earlier that one of the primary functions of the 
Network Layer is that of routing, or getting packets from 
source to destination, regardless of network types and the 
number of nodes in between. The methods and algorithms 
involved in routing are numerous and complex, so we will 
deal with the simplest, so as to give you an idea of how they 
work, without going in to too much detail, (There are books 
written on routing algorithms, so if you would like to get into 
more detail, a visit to the computer section of a well-stocked 
bookstore can get you all the detail you would wish for, and 
then some.) 

The routing algorithm is what decides how a packet will 
travel from a given router. If datagrams are used, this 
decision is made for every packet, If VCs are used, then this 
decision is only made during the connection establishment, 
and the packets follow tills route. This type of VC routing is 
also called session routing, as the route is used for the entire 
session. No matter which type of routing is used, there are 
certain goals for any routing algorithm: correctness, 
simplicity, robustness, stability, fairness, and optimality. 

The first two iiems are fairly obvious. The algorithm must 
be correct, otherwise, the packets will never be delivered 
correctly. It must also be as simple as possible, so that it can 
be fast enough to handle the loads placed upon it. The third 
property, robustness is not as obvious, but some routers are 
in place for years at a time. The algorithm used by a router 
must be able to handle failures by the other devices it directly 
deals with, changes in topology, protocol, numbering 
scheme, etc. It must be able to do this without requiring 
human intervention or attention as well. Stability is also 
somewhat obvious. The algorithm must not cause problems 
due to the way it functions, otherwise it is not useful. 

The final two are harder to reconcile with each other. 
Fairness dictates that no one part of the subnet be used to the 
point of saturation, yet choosing a route based solely on the 
optimal route may Indeed cause this to happen. Even 
optimization can result in conflict, as minimizing packet delay 
does not always maximize network throughput. To help with 
this, and to deal with fairness, most algorithms concentrate on 
minimizing the number of hops a packet must make. This 
helps minimize delay while maximizing utilization. 

While tliere are many algorithms, they all fall into two 
basic camps, static and adaptive algorithms. Static algorithms 
are decided outside of the router, and either downloaded to 
live router when it is booted, or manually entered on the 
router. If you have ever manually entered routes on products 
such as TPNet Router, or Soft Router, that is a type of static 
routing. Adaptive algorithms change routes based on 
information received from adjacent devices that inform them 
of the opening of a new route, or the closing of an existing 
one. These maintain their own routing tables, and do not 
require manual intervention to update themselves. 
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Algorithm Examples 

Of the static algorithms, flooding is the probably the 
simplest. In a flood routing setup, an incoming packet is sent 
out on every single line the router has except for the one it 
came on. Now, obviously, the potential for bringing down a 
network through a potentially infinite number of packets on 
the network. So there are some techniques to avoid this, such 
as inserting a hop counter in the header of each packet, 
decrementing it each time it passes through a router, and 
discarding the packet once the hop count is equal to zero. 
Another technique is to set up each flooded packet with a 
sequence number. The source router then has to provide the 
subsequent routers with a packet list, so they know which 
packets have been flooded, and they are not re-flooded. 
Another variation is selective flooding, where packets are 
only flooded in the appropriate direction. (Le., a westbound 
packet is not flooded back east. ) Although flooding may seem 
to be of little use, for the military, or other organizations that 
need to be able to bypass dead, or blown up routers, flooding 
is a quick, simple method to do just that. As well, flooding 
always chooses the shortest path, because it chooses every 
path. Consequently, if the flooding overhead is ignored, 
flooding actually produces the smallest delay of any algorithm. 

Anther static algorithm is shortest path routing. Simply 
put, with this algorithm, the subnet is displayed as a graph, 
with each point on the graph representing a router or end 
node, and each segment on the graph a communications line 
between points. The algorithm then determines the shortest 
path, and sends the packet on its way. There are a number 
of ways to determine exactly what is meant by ‘shortest*. The 
most common is to find the path that has the least number of 
hops. However* this can break down, especially when a two- 
hop path is a hundred miles, and a four - hop path is fifty 
miles, To avoid this, shortest path routers actually use hop 
count, geographic distance, queuing and transmission delays, 
etc, to find the true shortest distance. Each factor is given a 
weight, and that weight is used to find the shortest path. 

The disadvantage to static routing is of course, that it’s static. 
It cannot take advantage of improved conditions, or handle 
worse conditions. It can only route the way it knows. So much 
of today’s routers use dynamic algorithms, that can adapt to 
current conditions on the network, without human intervention. 
Since these are much more complex than static routing, we will 
only look at one of them, distance vector routing. 

Distance vector routing algorithms function by having 
each router keep a table, or vector with the best known 
distance to each destination, along with the associated lines. 
The routers update the vector tables by exchanging 
information with their neighbors. This type of routing is one 
of the oldest, being not only the original ARPANET routing 
algorithm, but also used as the RIP algorithm, and by 
DECNet, IPX, AppleTalk, and Cisco routers. 


The vector tables maintain certain parameters about each 
route. The entry for each route has the line to be used for 
that destination, and the estimate of the time to that 
destination. This time can be a measure of the hops to the 
destination, time delays, queue lengths, etc. The router is 
also assumed to know the distance to each neighbor. If the 
metric is hops, then there is only one hop. If queue length is 
used, then the router analyzes each queue. If delay is used, 
then the router measures this. 

Although distance vector routing works well on paper, 
the real world implementations can have problems, 
particularly w r here updates are concerned. Although distance 
vector routing reacts well to improvements in the subnet, it 
can take much longer to react to bad news. Especially if time 
delays are used, and a node or router is down, (giving it a 
time delay of infinity), propagating that throughout the 
subnet can end up taking an extremely long time, hence the 
name for the problem, ‘count to infinity’. 

Conclusion 

There are a lot of uses for the Network Layer, most of 
which I have avoided, as they tend to get into specific 
protocol types, or network types, and 1 wanted to stay away 
from any one protocol But if there is any sort of routing 
going on, regardless of protocol or network type, it is most 
likely being done at the Network Layer level. 1 hope that you 
have an idea of the differences between connection - 
oriented, and connectionless services, and also a basic 
understanding of routing, and routing algorithms. Again, I 
avoided getting into the math of the algorithms, as that could 
easily take up an entire magazine, and is of more use to 
those folks writing router software, If, as a network manager, 
you understand what a router is trying to do, and why, you 
will find that troubleshooting, and designing networks will 
be noticeably easier, and the reasons w r hy networks need to 
be set up in a given fashion will probably make a lot more 
sense to you. Our next article will deal with the Transport 
Layer, which is not only at the heart of the OS I model, but of 
most other protocols as w r ell. As always. 1 encourage you to 
delve into these things on your own as well, using not just 
my bibliography sources, but any other books you may find 
on the subject. 

Bibliography and References 

* Tannenhaum, Andrew S. Computer Networks, Third 
Edition Prentice Hall, 1996 
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Cubby: Multiscreen Desktop VR Part II 


How to create an Input 
Sprocket driver for a 3D 
input device 


Summary 

In this second part of our 'Cubby; 
Multiscreen Desktop VR’ trilogy, we will 
introduce you to the art of creating a 
driver to read an Origin Instruments 
Dynasight input device, With the 
Dynasighu the position of the head of 
the user is established so that Cubby can 
display the correct images on its 
screens. The driver is created with 
InpuLSprocket, which is part of Apple's 
Game Sprockets API. 

Introduction 

In our previous articles about 
Desktop VR (Djajadiningrat & Grihnau, 
199$; Grihnau & Djajadiningrat, 1998), 
we used the Pointing Device Manager 
(PDM) of QuickDraw 3D to serve our 
input needs. We promoted the PDM 
because it was intended to support 3D 
input devices. The PDM and 
Input Sprocket have in common that they 
both separate the device dependent code 
from the application. They relieve 
application programmers from dealing 
with devices directly and provide an 
abstraction layer for input programming. 


The difference between the two is that Inpu [Sprocket is 
actually supported by device manufacturers. There are no 
QuickDraw 3D drivers available to our knowledge. For 
InputSproeket on the other hand, lots of drivers are available. 
In addition, InputSproeket has configuration management built 
in, A standard interface is provided for connecting devices to 
applications, For these reasons InputSproeket provides a better 
solution for Cubby’s input needs than the PDM. 

In this episode we cover programming with 
InputSproeket to create a device driver, In the next episode 
the application side will be covered. Together, the two 
articles cover the whole of InputSproeket. The driver we 
describe is for the Dynasight device. If you do not own one 
or plan to buy one, you might still be interested because the 
techniques explained here can be used for other input 
devices as well. Documentation on writing InputSproeket 
drivers is scarce, so you might pick up some facts here. To 
compile our code, you will probably need to download the 
latest version of InputSproeket from the Apple web site (see 
References section), which is currently version 1,7.3- 

[f you are Familiar with programming drivers for 
InputSproeket, you can safely skip the next section and proceed 
with the following section about creating an InputSproeket 
driver for the Dynasight. If InputSproeket drivers are new to 
you, you can read the next section and be introduced to the 
basic concepts. If you have worked with InputSproeket before 
but not with drivers, you can also read the next section to learn 
how drivers and applications communicate. 

Introduction to InputSpbocket 

The goal of InputSproeket is to make life easier for game 
programmers who deal with input devices. There are an 
immense number of devices on the market with different 


Maarten is always jealous of his co-author, The ease with which Tom creates a funny "about the author 1 piece starts to become 
almost traumatic. He is now on the verge of refusing to finish Ins contribution to the final episode. You might try to inspire 
him with an email at; M.W.Gribnau@io.tuddit.nl. 

'There are some striking similarities between Tom and his Wallstreet PoBo. You need to push them really hard to wake them 
from sleep, if you persist it still takes ages before they finally get into action, and sometimes it appears as if they've woken up 
bur really all they do is zombie around in some undefined state in which it is impossible to get anything sensible out of them. 
If they're up and running you can reach them at J.R Djajadin in grat@io.tuddft.nl. 
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features. Trying to have a game support all these devices 
optimally can lead to severe headaches. Most games support 
input devices through emulation of the keyboard and mouse. 
But emulation does not suffice when supporting complex 
devices that have directional pads, levers, wheels, etc. For one, 
the game cannot take advantage of the extra input controls of 
complex devices and secondly, configuring the devices and 
connecting them to game controls is device specific. That 
means that game programmers should provide configuration 
capabilities for each device that they need to support. 

This is where InputSprocket comes in. It solves these 
problems through an input device architecture that allows 
games developers to create games that can use a wide variety 
oF input devices. Input device developers can use 
InputSprocket to build device drivers that provide a 
description of input device controls that the game can use to 
automatically configure its control options. The device driver 
can also provide a user interface that allows die user to 
change default control options. Therefore, game programming 
is made easier because a lot of device dependent code is 
moved from the application to the device driver. 

The communication between InputSprocket drivers and 
games is based on elements. The element is a building 
block used to describe the capabilities of a device. Each 
control of a device is described with an element, so every 
device can be described with a set of elements. For example, 
a one-button mouse can be described with an element for 
the x-axis, an element for the y-axis and a button element. 
More complex devices may require more elements but are 
handled in the same way. An element is described by the 
following three pieces of data. 

A human readable identifier is a string that the game 
can display to identify the element for the user during 
configuration. Examples of such identifiers are “trigger”, 
“roll” or “move forward". 

The element kind is a four-character sequence that 
indicates the type of data the element produces. For 
example, button elements will typically produce two-state 
values while axis elements produce Continuous data. 
InputSprocket currently provides five basic element kinds: 

• Button elements produce two-state data. 

• Directional pad dements are nine state elements with an 
idle position and eight states corresponding to the eight 
directions on a typical directional game pad. 

• Axis elements produce continuous data, either with or 
without a meaningful center. A symmetrical axis has a 
meaningful center, like the axis of a joystick. Axis 
elements such as a gas pedal or a brake do not have a 
meaningful center. 
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Dynasight 


■ Delta elements are like axis elements but instead of an 
absolute position or orientation, they produce Delta data, 
which indicates the distance moved relative to the 
previous position (e.g, mouse axes). 

* Movement elements produce movement data that is given 
both as x-y axis data and directional pad data, allowing 
the game to use whichever is suitable. Note that in 
general you should use axis data instead. 

There is a sixth element kind, the virtual element, which 
we will encounter later. 

The label of an element gives the suggested use for an 
element. For example, a button element may be intended as 
the start button or the firing button. During configuration, a 
game uses labels to find the elements it requires for play. 

As was mentioned, elements are the way applications 
communicate with drivers. There are two interfaces to pass 
data from drivers to applications using elements: the low-level 
and the high-level interface. In principle, driver programmers 
can decide which interface to implement. It is tempting to 
implement the low-level interface only, since it is the easiest to 
impl e men L. Howe v er, d ri v e rs shou Id prc>v id c be>t h tiie It > w a nd 
the high-level interface, so that game application programmers 
can decide which interface they want to use. 

Low-level Interface 

The low-level interface is the simplest to implement 
when building drivers. Figure I shows a diagram of both the 
low and the high-level interfaces. The lower parts of the 
Dynasight Driver and the InputSprocket Hxtension represent 
the low-level interface. Cubby uses only the high-level 
interface and therefore connects the cameras to the high-level 
axis elements (Head X, Head Y and Head X) exclusively. 
When the driver is loaded, it creates elements for every 
control it has. The driver is responsible for reading the data 
from the device and, as soon as it is loaded, should update its 
elements every time the device reports new data. Applications 
can connect via InputSprocket directly to the elements of the 
device and update the game state accordingly. 

Want to suggest an 
article for the 
magazine? 

Send your 
suggestion to 
editorial@mactech.com 
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Figure 1. Diagram of the low- and high-level interfaces . 
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High-level Interface 

In Figure 1, the upper parts of the Dynasight Driver and 
die InputSprocket Extension represent the high-level 
interface, The high-level interface is somewhat more 
complicated than the low-level interface but it has all the 
advantages that InputSprocket was meant to offer Instead of 
connecting to the device’s elements directly, games read data 
from the devices through virtual elements. These virtual 
elements are created by InputSprocket from the needs that 
the game has. Drivers are responsible for the mapping of 
needs to virtual elements. The high-level interface Is only 
valid between the driver’s Init and Stop callbacks that 
InputSprocket calls. Only the driver knows exactly how it has 
been configured, and when it is active, it is responsible for 
pushing data to those virtual elements for each need for 
which it is configured. 

Configuration 

The majority of driver callbacks are related to the 
Configure dialog. These function calls will only happen 
while the high-level is valid (he. ISpInit has been called 
without a subsequent ISpStop). When the application calls 
ISpConfigure, a dialog is presented with a scrolling list of 
devices with one device selected. Figure 3 shows this dialog 
with our Dynasight device selected. The popup menus show 
the current connection of the Dynasight x- y- and 2 -axis to a 
game’s roll, pitch and yaw controls. The selected device is 


responsible for the primary pane of the dialog, handling all 
events and drawing related to that area. The GetSize function 
is called to determine the preferred and minimum sizes of 
the pane area used by the device. If the pane area will not 
fit on any available display device, then that device is 
removed from the high-level list, The Begin Configuration 
function is then called for each device. The configure dialog 
is resized and shown. The Getlcon function is called for each 
device to determine the icon to be shown in the scrolling list. 
Then the Show function is called for die selected device. This 
is the time to call AppendDITL for the resources to be 
displayed in the primary pane. All events returned in the 
dialog filter are passed to the H and feEvent function to give 
the device a chance to handle them. If update events are not 
handled (the recommended option to avoid extra flicker), 
InputSprocket will make the device Draw function call from 
within a Begin Update EndUpdate pair. Unhandled mouse 
clicks will be passed to the Click function. If the device called 
AppendDITL to add items to the dialog and those items are 
returned by InputSprocket’s ModalDialog call, then it will call 
the DialogltemHit function. 

The device should maintain a 'dirty’ variable that is set 
whenever any configuration information is changed, and 
returned and cleared when the Dirty call is made. When a 
different device is selected in the list, the old device receives 
a Hide function call and the new r device a Show function call. 
When the dialog is closed, every device receives an 
EndConfiguration call. 
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Figure 2. InputSprockets's configuration dialog box with the 
Dynasight device selected. 


Procedure 

Figure 3 illustrates the sequence of events when a game 
is using InputSprocket. The initiating calls are shown on the 
left and the driver's responses are found on the right. There 
are four major activities. Low-level initialization is entered 
when an application calls ISpStartUp. InputSprocket wall then 
load the driver and call its major entry point. In response, the 
driver should look for devices present on the system and 
create InputSprocket devices for each active device. If a 
device was created, InputSprocket will call the driver’s Meta 
handler to Find out where the driver's entry points are. If no 
InputSprocket device was created, the driver is unloaded. 
High-level initialization is entered when the application calls 
ISpInit. InputSprocket passes the needs and virtual elements 
to the driver. In response, the driver stores them and does an 
auto-configuration. This means that the driver will try to find 
an optimal match between the needs of the application and 
the elements the device has. When the high-level interface is 
valid, the application can call ISpConfigure. This starts the 
configuration activities explained in the previous section. 

There are several guidelines that should he followed 
during auto-configuration. If a previous device fulfilled a 
need and the kl$pNeedRag_NoMultiConfig hit is set in the 
need structure for that need, the device should not attempt 
to autoconfigure to the need. The driver should indicate that 
it is fulfilling a need so that devices queried later knew that 
the need Is taken. More guidelines can be found in Apple’s 
documentation of InputSprocket (see References section). 
After auto-configuring, the device should immediately push 
initial values to the corresponding virtual elements and from 
that point push data to those virtual elements whenever data 
is pushed to the elements to which they are configured. 

When the application calls ISpStop, the validity of die high- 
level interface ends. The drivers should stop pushing data to the 
virtual elements and dispose die needs and Lhe virtual elements. 
Calling ISpShutdown within the application causes InputSprocket 
to call the driver’s termination routine. In response, the driver 
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Figure 3. The sequence of events in communication 
between driver and game . 


Creating an InputSprocket Driver for the Dynasight 

Now that we have a basic understanding of how InputSprocket 
works, we will dive into the coding of a driver and illustrate how we 
can put this knowledge to use. We Like the Dynasight device as 
example and star! with the real driver functionality: the initialization 
and transfer of data. The configuration of the driver wall covered 
in the next section. The Dynasight device is an infrared tracking 
device that Is used in Cubby to track the head position of users. The 
3D position data is made available on the serial port. In the 
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following discussion, we will not go into ihe details of reading the 
position data from the serial port. If you are interested in that pail of 
the driver, you can read our previous article about Desktop VR 
(Gribnau & Djajadiningrat, 1998) and/or you can have a look at the 
code accompanying this article. 

Before we begin, we should make some general remarks about 
developing InputSprocket drivers. An inputSprocket driver is a 
shared library with a specific file type and creator ('shlb T and 'insp 1 ). 
All drivers must be located in the same folder as the InputSprocket 
extension, which must l>e the Extensions folder. Being a shared 
library, it takes some extra effort to debug a driver. First of all, you 
should set the ou tput directory of your development environment to 
die Extensions folder of the System folder on your startup disk, so 
that the compiled driver ends up there. Secondly, you should set a 
hast application dial is used to run tlie driver. 

The Dynasight driver handles tile six major tasks that all 
drivers should handle: shared library initialization, shared library 
termination, pushing data, high-level' In it, 'high-level 1 Stop, and 
the configure dialog user interface. The code for shared library 
initialization is shown in Listing L This routine is called when 
InputSprocket loads the driven The important parts are that the 
driver checks whether a certain version of InputSprocket is 
available. If version 1.2 or greater is not available, the driver 
returns without creating any InputSprocket devices. In that ease, 
InputSprocket unloads the driver. The other important point in 
this listing is that the driver retrieves the file specification of the 
shared library. The file specification is used in the driver 
initialization routine in locate the resource file. 


Listing 1: ISpDnverDynasiglitMain.cp 

_myinUalf/x 

QSErr _myinitialize(CFraglnitBlDckFtr ibp) 

t 

QSErr ^rr — noErr; 

FSEpec fileSpec D 10 r 0 4 01: 

NuaVerslon version: 

UInt32 inp'utSprocketVersion; 

#if _J1WERKS_ 

err = _initialize{ibpJ ; 

if (err !“ noErr) ( 
return err; 

1 . 

#endif 

//Require InputSprocket 1.2.0 

version - ISpGetVersiont); 

inputSprocketVersioii - k (UInt32 * j &(version); 
if (inputSprotkelVersion ( QxQ120GQ(J0) ( 
return err: 


// Grab the file spec 

if {ibp-HragLocator .where — kOataForkCFragLocetor) ( 

//llic shared library should always be localed in die data fork 
fileSpec - *ibp-2frag,Locator, u.onDisk,fileSpec : 

I 

// Create IS device for each Dynasiglu device found on die system 
// If we don't create an IS device, IS will unload us 

Dynasightlnit(fileSpec): 
return err: 

1 

In Listing 2, it is shown what happens inside the 
Initialization routine. The routine looks at all available serial 


ports for a Dynasight. II' one is found, the driver’s resource file 
is opened and a structure in a global array (fDynas) is filled with 
all the information for the device on the current port. After 
setting some default values in the structure, the InputSprocket 
device is actually created (by calling CreateDevice) and the 
Dynasight is pul into action. Finally, after all ports have been 
checked, the resource file of the driver is closed. 


Listing 2: ISpDfiverDyn asight.cp _ 

Dymsightlnir 

OSErr DynasightInit(FSSpec fileSpec) 

I 

OSErr err; 

short resourceRef = -1: // nef to our resource file 

Boolean resourceFileOpen = false; // true if our resource file is open 
SerialPort port; 

Ulntlfi portlD, nuniPortlDs: 

Boolean portWithDynasight; 

fNuniDynas = 0; 

numPortlDs = port.GetMumSerialForts(); 
for (portlD = 0; portlD i numPortIDs; portlD-H-) I 
I 

Dynasight dynasight: 
portWithDynasight = 

dynasight.Ge'tDvnasightFoundOnPnrt fportlD); 

) 

if (portWithDynasight) ! 

// Open the resource file and cheek for errors 
if £IresourceFileQpen) ( 

resourceRef - FSpdpenResFitaC&fiieSpec, fsRdPerm}; 
err - ResError(): 
if (err 3 = noErr) l 
return err: 

I 

resourceFileGpen & true; 

] 

fDynaa [fNvmDynasI ,dyria.>igbt - new Dynasight (portlD): 
fDyoaE [fNuinDynasi . fileSpec = fileSpec; 
fDynas EfNmDynasj .oldLLStale*xAxis = kiSpAxisMiddle; 
fDynas [fNumDyn^H , • 1 dt.LS i n , yAx i s = klEpAxisMiddle; 
fDynas [fNumDynas. . iILLSrr-rr e. zAxis klSpAxisMiddle; 

LnwToHighLeveIStatefDynasf INurnDynas].oldLLState, 
ifDynflfi[s].oldHLStatej; 
fDynas [fNmnDynas] .axialndexToNeeds LkAxisIndex_XAxis] ir 
kdnsetlndex; 

fDynas[fNunDynasl.axisfndexTofJeeds|kAxisIndex_YAxis]- 
kdnsetlndex; 

fDynas [fNutuDynafll, axisIndexTaNeeds[kAxisIndex_ZA3d.fi] = 
kdnsetlndex: 

fDynas I fNumDynas i , virtualElemeiytsValid - false; 
fDynas[fNumDynas].active ^ false; 

// Create the device and store its reference 
CreateDeviceCfiifDynas [fNuniDynas]): 
fDynas[fNumDynas].active “ true; 
fDynas [fNumDynas] . dynasight - )StartRunning ( 

MyDynasightCompletionProo, &fDynas [fNuraDynas]); 
fNumDynas-H-; 

1 

// Close the resource tile 

if (resnurceFileQpen) I 

ClosaResFile(resourceRef): 

1 

return err; 


The Create Device routine actually creates tlie device and 
elements for the low-level interface. The driver provides three axis 
elements, corresponding to the x- ( y- and /-axis of the Dynasight 
device, In our driver we chose to set up the device using a resource 
(of type Isdv'), as shown in Listing 3- This resource contains all die 
information of an ISpDeviceDefinition structure that is passed to die 
InputSprocket. Listing 4 shows the creation of an axis element 
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Again, we chose to set up the axis elements from a resource (of type 
*iseD that contains the information in an ISpElementDefinitionStruct 
structure which is needed to set up an element After retrieving die 
element resource, yet another resource is retrieved This is die 
dement configuration resource (of type *iseP) dial is used to 
configure the element. This part is optional. If die resource is not 
available or invalid, the dement is still created in die subsequent 
ISpElement_New call. 

Listing 3: ISpDriverDynasightep 

(; rt;i i e l )c\ ic c J 'n j mlltrst j u ret 

OSErr CreateDeviceFromResource( 
short resld, 

UInt32 refCon, 

ISpDeviceReference ^device) 

( 

Handle hi 
OSErr err; 

ISpCevlceDefinltion def: 

// Read the device resource from the res file 

h - Get 1 Resource(’iady'. resld): 

err * ResError(); 

if (err 1“ noErr) I return err; I 

if {h — nil) I err - -1: \ 

if (err 1“ noErr) ! return err; I 

// Copy the handle to ;e structure and release the handle 

BlockkoveData{ *h, 4def t sizeof (,def)) r 

ReleaseResource(h]; 

// Create the InpuLSprocket device 

err = ISpDevice_Nevr(kdef t (lSpDriverFiinctionPtt:_MetaHandler) 
DeviceMetaHandler, refCon, device); 

return err; 


Listing 4: ISpDr iver Dynasi g htcp 

C reateHemen tFn m Re so urce 

OSErr CreateElementEromResotirce( 
short elementResId, 
short eonfigResID, 

ISpDeviceRefetence device. 

ISpElementReference * element) 

I 

Handle hi; ft handle to resource based dement definition structure 

Handle h2; // handle to resource based element configuration info 

OSErr err; 

I SpE lenient Def initionStruct def; // actual dement definition structure 

// Read the dement definition struct from a resource 

hi - GetlResource( 1 isel", elementResId); 

err - ResErrorO: 

if (err != noErr) I return err; I 

if (hi = nil) \ err = *1; \ 

if (err != noErr) f return err: I 

// Copy the handle to a structure 
BlockMoveData(*hl, &def» sizeof(def)): 

// Reatl the configuration information from a resource (this may fail) 

h2 = GetIResonrce{ f isef, configResID): 
err - ResError[): 
if (h2 && (err = noErr)) I 
HLock{h2); 

def.cotifiglnfa “ *h2; 

def.conflglnfoLength = GetHandleSize(h2); 

1 

// Create the InputSprocket dement 

def.device = device; 

err = ISpElesnent_New{&def, element); 

// Release resources 
HUnlock(h2): 

Re-leaseResource(hl): 

Releas@Resource(h2); 

return err; 
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When creating the device in Listing 2, a pointer to 
DeviceMetaHandler was passed to the ISpDevice_New routine. This 
routine is called by InputSprucket to retrieve pointers to all the 
callbacks in our driver. It is called after the initialization of the driver. 
Listing 5 shows a part of the DeviceMetaHandler. InputSprocket calls 
die routine with a selector. The routine selects the appropriate 
callback and returns it. This example returns only the pointers to our 
tnit and Stop callbacks. In our driver, the Meta handler returns 
pointers dealing with die configuration as well. These will he listed 
in die next section. 

Listing 5= Example of a device Meta handler 

DeviceMetaHandler 

ISpDriverFunctionPti'_Gen@ricj DeviceMetaHandler( 

UInt32 refCon, 

lEpMetaHaEdlerSeiector selector) 

I 

I5pDriverFunctionPtr_Generic function = NULL: 
ISpDriverFunctionPtr_Init funclnit; 

ISpDrlverFunctionPtr_Stop funcS top; 

switch(selector) I 

case kISpSeiector_Init: 

funclnit = (ISpDriverFunctionPtr_Init) Init; 
function = [ISpDriverFunctionPtr_Generic) funclnit: 
break; 

case kISpSelector_Stop: 

fimcStop = (ISpDriverFunctionFtrJStop) Stop: 
function • (ISpDriverFunctionPtr_Generic) funcStop: 
break: 

] 

return function: 


if (tdyna->active) (data->dynasi£htStatus — 

dynasightStatus_Track)) f 
time = iSpUptimeO; 

// Scale Dynasight coordinates between 0 and I 

NormalizeDynasightPositicrif^data->position< &yf, 

Azf): 

// Put point between USpAxisMinimum and IdSpAxisMaximum 

scale - kISpAxisMaximum - klSpAxisMinimum]; 

xf = klSpAxisMinimum + xf * scale: 

yf = klSpAxisMinimum + yf " scale; 

zf — klSpAxisMinimum + zf * scale: 

llState.xAxis = (Ulnt32)xf; 

llState.yAxis = (UInt32)yf; 

llState.zAxis = (UInt32)zf: 

// Push lowievel data lor Jow lcvd interface 
if (llState,xAxis 1= dyna->oldLLState.xAxis) \ 
err " ISpEleiQent_PiJshSimpleData ( 

dyna->deviceXAxis, llState,xAxis, fittime); 

f 

if (llState.yAxis 1= dyna ■ DolcLLState,yAxis) I 
err = ISpElement_PushSimpieDat:a ( 

dyna /deviceYAxia, llState.yAxis, &time): 

I 

if (llState.zAxis 1 = dyna >oldLLState.zAxis) I 
err 55 lSp£lement_FushSiitiplcData( 

dyna-MeviceZAxls, llStrte.zAxis, &time): 


// Push high-level data for high-level interface 
LowToHighLevelStateffcliState, fithiState): 
if (dyna•>virtualElementsValld) I 
SetVirtuaisData(dyna, khlSLate); 

1 

dyna >oidLLState = llState; 
dyna->oldHLState = hi State: 


The beating hart of the driver is listed in Listing 6. This 
is the routine that is called whenever there is new data 
available from the Dyna sight. We passed a pointer to this 
routine when we started the Dyna sight in Listing 2. In the 
routine, it is first checked whether the low-level interface is 
active and whether the Dyna sight is producing reliable data. 
Then, the position read from the Dyna sight is scaled between 
0 and 1 and subsequently scaled between InputSprocket axis 
values kiSpAxis Mini mum and kISpAxisMaximum. This is a 
requirement of InpuLSprocket. The convention is to scale 
coordinates of devices between those boundaries. For 
instance, with a joystick, klSpAxisMinimum should be sent 
when the joystick is fully rotated to one end and 
kISpAxisMaximum when ii is fully rotated the other way. 

The scaled coordinates are pushed to the low-level elements 
with the three ISpElement_Push Simple Data calls but only when a 
coordinate has changed. Then, the low-level data is converted to 
high-level data (in our case copied) and send to the virtual 
elements when the high-level interface is valid. 

Listing 6: ISpDriverDynasigliLcp 

M y Dynxsig J U< !o ntpEci ion Pith: 

void HyDynasightComple tlonP ro q( 

DynasightCompletionProcData* data) 

[ 

OSStatus err; 

AbsoluteTime time; 

TDynasightRecPtr dyna = (TDynasightRecPtr)data->data; 

TISpLovLevelState llState; 

TlSpHighLevelState hiState; 

float xf. yf, zf: 


InputSprocket Driver Configuration 

We will now show the important parts of the driver 
relating to the configuration dialog. For our Dyna sight driver 
this part is relatively easy since we have only three popup 
menus in the dialog box (see Figure 2). Each menu can be 
used to change the function of a Dynasight axis. For 
example, a user might select the menu and change the 
function of the x-axi.s from need pitch’ to need move 
forward’. The driver maintains the list of total needs of the 
application and a mapping of needs to axes. A selection in 
the dialog might change this mapping. 

As was mentioned above, the first routine InputSprocket 
calls when starting configuration is the GetSize routine. The 
driver returns the minimal and optimal size we need, as 
shown in Listing 7. The next routine called is the Get Icon 
routine shown in Listing 8, The driver returns the resource 
identifier of the icon suite of the Dynasight driver. 

Listing 7: ISpDriyerDynasight.cp 

Get Size 

OSStatus GetSize{ 

UInt32 refCon, 

Point *minimum. 

Point *best) 

( 

refCon; 

best-)h — minimum->b — 200; 
best->v = minimum->v = 120; 
return noErr; 

] 
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listing 8: IS pPriverPyn as ight.cp 

Getlcon 

OSStatus GetIeori{ 
tJInt32 refCon, 
short ‘iconSuiteResourceld) 
f 

refCon: 

•iconSuiteResourceld = klconSuiteDynasight; 
return noErr; 

\ 

When the Dynasighi device is selected is the dialog box, 
InputSprocket calls the driver's Show routine listed in Listing 9. 
This is the time to have our dialog items added to the main 
dialog pane. First, some information about the dialog is stored 
for later use On the Hide routine for instance). Then, the L DiTL r 
resource is retrieved from the resource hie and appended at the 
end. Listing 10 shows how the reverse takes place. The Hide 
routine is called when another device is selected in the dialog or 
when the dialog is closed Then, the driver removes its dialog 
items from the ‘DITL. 

Listing 9* ISpDriverDynasightxp 

Show 

OSStatus Show( 

UInt32 refCon,, 

DialogPtr theDialog, 
short dlalogltcmNumber, 

Reel *r) 

I 

OSStatus err; 

TDynasightRecFtr dyna = (TDynesightRecPtc} refCon: 

Handle ditl; 
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dyna->dialogRect = *r; 
dyna->dialogPtr = theDialog; 

dynaOdialogBaseDITLCount = CountUITL (theDialog); 

// Open the resource file, get our DHL and append it 

dyna->resFileRef “ FSpGpenResFile(Bdyna->fileSpec, 
fsRdFera); 
err = ResErrorU: 

If (err 1= noErr) \ return err: ] 

ditl “ GetIResource('DITL'. kDITLlD_Config); 

err = ResErrorC); 

if (err 1= noErr) i 

CloseResFile(dyna•>resFileRef): 
return err: 

I 

AppendDITL(theDialog. ditl t - dialoglteinNiiiiibe r): 

// Free our DITL 

RelesseResource(ditl); 

return noErr: 

I 


Listing 10: ISpDrivcrDynasight.cp 

Hide 

OSStatua Hide{ 

UInt32 refCon) 

l 

TDynasightRetPtr dyna = [TDynaeightRecFtr) refCon; 

// Restore to original count of items 

ShortenDITLCdyna->dialogPtr, CountElTL(dyrta->dialagPtr) - 
dyna■>dialogRaaeDiTLCount): 
dyna->dialogPtr = nil; 

CloseResFile(dyna >resFileRef): 
return noErr: 


When the dialog is on the screen, the driver needs to respond 
it j events to track whether there tire changes in the configuration. 
In our case, the driver has only popup menus that it can handle by 
responding to mouse click events. Therefore, our driver ignores all 
other events that InputSprocket passes. In listing 11, it is shown 
how the driver handles mouse clicks. First the position of the click 
is established. Then we iterate through our popup menus and call 
HandleAxisClick for each axis. This routine checks whether the 
current need of m axis changes as a. result of the dick. 


Listin g 11: ISpDrive rDynas igbt.c p 

Click 

OSStatus Click( 

Hint32 refCon, 

const EventRecord *event) 

l 

refCon: 

TBynaeightRecPtr dyna = (TDynasightRetPtr) refCon; 

Point where: 

Ulnt32 itr; 
short iteniNo; 

UInt32 oldNeed; 

where ” event■>whera; 

GlobalToLoca.1 (Swhere); 

for Citr = kDiaiogItem_FirstPopup: 
itr <= kDialogItem_KuaiPopups: 
itrH-J | 

iteirNo = itr + dyna->dialog.BaseDITLCourit: 
oldNeed = dyna■>axisIndexToNeedsIitr-1]: 
switch (itr) [ 

case kDialogItem_XAxis: 

HandleAxisClick [dyna, where, iteinNo, 

kISpEiementLabel_AxiB_XAxis, kAxisIndex_XAxis, 
oldNeed); 
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break; 

case kHialogItem_YAxis: 

HandleAxisCllck(dyna h where. itemNo, 

klS pE1emen tLab e l_Axi h_YAx is. kAxisInd ex_YAxi s , 
oldNeed); 
break; 

case kDialogIteni_ZAxig: 

HandleAxisCltckfdyna, where, itemNo, 

kISpEiententLabel„Axis_ZAxis, kAxisIndex_ZAxis, 
oldNeed); 
break; 
default: 
break; 

I 

] 

return fioErr; 

1 

Listing 12 shows the HandleAxisClick routine. First, it is 
checked whether the popup is actually hit and if the need for 
the current axis changed as a result of the click. If the need 
changed, the need for that axis is first cleared. Then, the new 
need is activated. The current configuration is marked klirty' as 
InputSprocket requires. Finally, the popup menu is drawn with 
the new need setting to reflect the change in need for this axis. 


Listing 12: ISpDriverDynasighLc p 

HaodkAxisClick 

void HaudleAxisCHckt 
TDyuasightRecPtr dyne. 

Point where, 
short itenNo, 

J$pElementLabel elementLabe1, 

TAxialndex axislndex, 

UInt32 oldNeed) 
f 

UInt32 itemlndex “ itemNo - dyna->dialogBaseDITLCount; 

Hints 2 newNeed; 

if CCheckFopUpHit(dyna, where, itemNo, 

kISpElettieniKind_Axis, elemenrLabel, validAxisKinds. 
validAxisKindsCount f oldNeed, newNeed) && 

(oldNeed !“ newtSeed)) I 

dyuasightPtr■>axd_sIndexToNeed£ [axlslndexl = newNeed; 
dynasightPtr->configurationDirty “ true; 
PlotPopupIcon(dynasightPtr,axislndex + 1 + 
dynaaightPtrDdialogBaseDITLComit. ttNone); 

I 


Tliis concludes our coverage of the driver’s code for the 
configuration dialog. There are some pans of the driver that we 
could not cover such as auto-configuration. The interested 
reader can kxik at the full source code of die driver to see how 
dies Ls accomplished. 


Conclusion 

In this month’s episode, you have discovered how 
InputSprocket can he used to create a driver for the Dynasight 
device. We hope that this episode has illustrated die power of 
InputSprocket, To connect Cubby w ith die Dynasight, we could 
have used parts of the driver code and pasted them directly into 
die Cubby application code. That would have saved die time to 
write and debug the driver However, now dial we have a driver, 
we can use the same device with other InputSprocket-sawy 
applications (imagine looking around in a game with the 


Dynasight as head-tracking device.,. X Moreover, making Cubby 
support InputSprocket, we can use any 3D device with an 
InputSprocket driver for Cubby, 

In next mondTs episode, we will cover the integration of 
Cubby with InputSprocket. We will show you how Cubby uses 
InputSprocket to move the cameras from part I. In addition, we 
will cover calibrating Cubby so that Cubby positions the cameras 
such dial the correct images are generated. 
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i PROGRAMMER'S 
CHALLENGE 


by Bob Boonstra , Wesiford, MA 


FreeCell 

Those of you who spend time on the Dark Side might have 
encountered a solitaire game called FreeCell packaged with a 
prominent operating system by Mr Bill. Your Challenge this 
month is to produce a FreeCell player. 

The prototype lor the code you should write is: 

typedef enum f 

kNo5uit=Q, kSpade, kHeart, kDiamond, kClub 
I Suit; 

typedef enum t 
kNoSpot“0. 

kAce, k2. k3, k4* k5 * k6, k7, k8, k9* klfl* 
kJack* kQueen* kKing 
1 Spot; 

typedef struct Card 1 

Suit e j it; /"the suit of the card, kSpadc .. kClub 7 
Spot spot; f* the spot af Ihe curd. kAcc .. kKing 7 
\ Card; 

typedef emun f* places to move cards from 7 

sFreeCellA-2 , sFreeCellB.sEreeCellC.sFreeCelTB. 

sTableauO-6,aTableaul,sTableauZ,sTableau3,sTableau4.sTableauS 
Tableau6 + ^Tableau/ 

] Source; 

typedef enuui (* places to move curds to 7 
dHome^I. 

dFreeCellA=2,dFreeCellB.dFreeCellC,dFreeCellD. 
dTableau0^6,dTab1eaul*dTableau2,dTableau3, 
dTableauA t dTableau5,dTableaub.dTabIeau 7 
1 Destination; 

typedef struct Move I /* move li card from ihcSourtrc to the Destination 7 
Source theSource: 

Destination theDestination: 

| Move: 

typedef struct Tableau i f* each Tbblcuu can contain 0..13 cards 7 
Card theCard [ 13]; 

\ Tableau; 

long t numMoves 7 FreeCell ( 

const Tableau theTahleau [6] . t the curds us initially dealt 7 

Move theMoves H # P return your moves in order here 7 

long ntaxMoves P storage b p reallocated for maxMoves theMoves 7 


The FreeCell game i.s different from many solitaire games 
in a couple of respects. First, all of the cards are visible, so 
winning the game is more a matter of strategy than of luck. 
Second, while there are FreeCell deals that cannot be solved, 
nearly every' game can be won, as contrasted with less than 
half of other popular solitaire games. 

FreeCell starts with the playing Cards dealt face up into 8 
piles called Tableaus, All 52 Cards are used, which means that die 
first four Tableaus receive seven Cards, and the remaining four 
Tableaus receive six Cards. The object of the game is to move all 
of the Cards onto four “Home” piles, one for each Suit, played 


in order from Ace up to King. You also have available four 
temporary' locations, or “Free Cells”, each of which can hold one 
Card. A Move consists of one of the following: 

moving an Ace from a Free Cell or from die top of a 

Tableau to an empty Home pile 

moving the next higher Card of a Suit from a Free Cell 

or from the top of a Tableau Lo the Home pile for that 

Suit 

moving a Card from the top of a Tableau to an empty 
Free Cell 

moving a Card from the top of a Tableau or a Free Cell 
to an empty Tableau 

moving a Card from the top of a Tableau or from a Free 
Cell to the top of a Tableau, where the Suit of the Card 
on top of the destination Tableau has the opposite color 
of the Card being moved, and where the Spot of the 
Card on top of the destination Tableau is one higher 
than the Spot of the Card being moved. 

Cards can be moved to or from a Free Cell, but each Free 
Cell can hold only one Card. Cards can be moved to the Home 
piles, never back from the Home piles. Cards can be moved to 
or from die top of a Tableau, but they can only be moved to a 
Tableau if the Suit colors alternate and if the Card value (Spot) 
decreases by one. Any Card from a Free Cell of the top of 
another Tableau may be placed on an empty Tableau, 

Your FreeCell routine will be called with the Cards dealt into 
the 8 Tableaus, Your task is to generate a sequence of Moves that 
solve the puzzle, returning them in theMoves, Each Move consists 
of a Source and a Destination. It is not necessary to specify the 
Card being moved, because the Source uniquely identifies the 
Card at any given point in the game* FreeCell should return the 
number of Moves generated, or zero if you are unable to solve 
the puzzle. 

Your solution will lie awarded 10,000 points for each puzzle 
it solves correctly, and penalized I point for each millisecond of 
processor time required to solve the puzzle. 

This will be a native PowerPC Challenge, using Lhe 
Code Warrior Pro 5 environment. Solutions may be coded in C, 
C++, or Pascal 

This Challenge was suggested by Peter Lewis, who wins 2 
Challenge points for the suggestion. More information on the 
game FreeCell can be found at http://WWW.freecell.org, 
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Interactive, AT&T Sys V. QNX, 88OPEN. FreeBSD, Windows 95/98/2000/NT, Lynx, Banyan 
Vines, and more... 


FairCom has been providing fast, flexible and scalable database development tools to the commercial 
developer lor over 20 years. During this lime FairCom has been utilized within countless embedded 
appliances, web server development projects and many vertical market applications. By offering industry 
leading performance, unsurpassed multi-user data availability and a complete transaction enabled database 
Server, FairCom provides the depth and breadth of technology to fit all of your database development 
needs. Add FairCom to your toolbox today. 


o 

Embedded 

Hardware 


c-tree Plus 9 

* Industry 1 leading performance 

“ Seamless cross platform migration 

■ Unsurpassed multi-user data availability 
" Complete source code 

* Portable threading API 

* Thread safe libraries 

* Low total cost of ownership* 

FairCom 9 Server 

* Powerful multithreaded database server 

■ Available for over 25 platforms 

■ Robust heterogenous network support 


application benefit 


Internet Smalt 
Appliances footprint 

Medical Stable 
Devices 

Factory Includes Full 
Automation Source Code 


Web 

Development: 


APPLICATION BENEFIT 


Dedicated Robust 
Web Server Threading 

B2B Server Flexible 

Communication 


Inventory Scalable 
Control 

Point of Sale Cross 

Ptutform 


- Mix and march clients and servers 

■ Multithreaded client support 

■ Full transaction processing 

■ Automatic file recovery 

• Very small RAM and disk footprint 

• Easy installation/configuration 

- No DBA required 

• Much more! 


Space Proven 
Exploration Technology 


FairCom Offices 


USA 

573.445.6833 

EUROPE 

+39.035.773.464 

JAPAN 

+81-59.229.7504 

BRAZIL 

+55.113872.9802 



...IN ONE CONVENIENT 
PACKAGE FOR ONLY $S9S 



CORPORATION 

Commercial Database Solutions Since 1979 


www.faircom.com/mac • USA. 80Q.S34.B180 • info@faircom.com 


Other company and prodLct names ere registered Erademfrks or trademarks Dt tfiBir respective owners 


© aODQ FarCom CorporaDan 































Three Months Ago Winner 

Congratulations once again to Ernst Munter (Kanata, 
Ontario) for submitting the winning entry to the August Longest 
Word Sort Challenge. Ernst's entry was the fastest of the seven 
entries submitted, and was just under 40% faster than the 
second-place entry by Jonny Taylor. 

The Longest Word Sou Challenge required contestants to 


Top Contestants 

Listed here are the Top Contestants for the Programmer's 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants. 


sort a sequence of lines of text based on the length of words 

Rank 

Name Points 

Rank Name Points 

in each line. The line with the longest word w r as to be 

1. 

Munter, Ernst 

243 

5. Shearer, Rob 

51 

considered greater than any other line. Among lines with 

2. 

Saxton, Tom 

106 

6, Boring, Randy 

50 

longest words of the same length, the comparison w'as to be 

3. 

Maurer, Sebastian 

68 

7, Taylor, Jonathan 36 

based on the next longest word, etc. Among lines with words 

4. 

Rieken, Willeke 

65 

8. Browm, Pat 

20 


of exactly the same length, the order was to be based on an 
alphanumeric comparison of words, in order of length, and 
then in order of occurrence. 

The key to Ernst's solution is the Line Descriptor that he uses 
to profile each line of text. The LineDescriptor contains a packed 
description of the number of words of each length contained in 
the line. This allows Erast to compare lines by comparing the 
numeric line profile values, using a single subtraction in the 
LineDescriptor:; IsLessThan routine to compare die number of 
words of several lengths. In the event the LineDescriptors match 
exactly, the CompText routine compares the words of each line 
as text, in order of word length. This Challenge allowed the use 
of assembly language, and Ernst used one line of it in the 
BitsNeeded routine, which is used by Text:;ComputeFietdSizes to 
calculate the width of the packed field needed to hold the 
number of words of a particular length. 

jonny Taylor's second-place solution uses a combination of 
sorting techniques, starting with a radix sort to partially sort the 
list based on the lengths of the 16 longest words in each line, 
and then using a quicksort algorithm to sort groups of lines with 
identical word lengths. Jan Schotsman s third place solution uses 
a merge sort to compare groups of up to 32 lines, shirting with 
a comparison of the lengths of the 16 longest words in each line, 
and resorting to a more careful comparison when necessary. 
This Challenge certainly produces an interesting variety of 
approaches to an unusual sorting problem. 

The table below lists, for each of the solutions submitted, 
the cumulative execution time in milliseconds. It also provides 
the code size, data size, and programming language used for 
each entry. As usual, the number in parentheses after the 
entrant's name is the total number of Challenge points earned in 
all Challenges prior to this one. 


... and the Top Contestants Awaiting Their First Win 

Starting this month, in order to give some recognition to 
other participants in the Challenge, we are also going to list the 
high scores for contestants who have accumulated points 
without taking first place in a Challenge. Listed here are all of 
those contestants who have accumulated 6 or more points 
during the past two years. 


Rank 

Name Points 

Rank 

Name Points 

9. 

Downs, Andrew 

12 

17. 

Wihlborg, Claes 9 

10. 

Jones, Dennis 

12 

18. 

Hala, Ladislav 

12. 

Duga, Brady 

10 

20. 

Schotsman, Jan 

13. 

Fazekas, Miklos 

10 

21. 

Widyatama, Yudhi 7 

15. 

Seiengut, Jared 

10 

22. 

Heithcock, JG 6 

16. 

Strout, Joe 

10 




There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution on (3) being the first person to 
suggest a Challenge that 1 use. The points you can win are: 


1st place 

2nd place 

3rd place 

4th place 

5th place 

finding bug 

suggesting Challenge 


20 points 
10 points 
7 points 
4 points 
2 points 
2 points 
2 points 


Name 

Time 

Code 

Data 

Lang 


(msecs) 

Size 

Size 



Ernst Munter (631) 

168 

3384 

330 

C++ 


Jonny Taylor (26) 

272 

14068 

44 

c 


Jan E. Schotsman 

337 

7256 

56 

c 


Rob Shearer (47) 

417 

426l6 

965 

C++ 


Darrell Walisser 

630 

4124 

128 

c 


Ladislav Hala (7) 

638 

3128 

2429 

c 


Ron Nepsund (47) 

972 

6492 

501 

c 



Here is Ernst’s winning Longest Word Sort solution: 

LongestWordSort. 

cp 


Copyright © 2000 

Ernst Munter, Kanata, ON, Canada 

r 

ITie Problem 


Test is to be sorted by lines, with the lengths of words as well as die text itself 
determining the order of lines. 
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Solution 


The text is analyzed, and a line descriptor derived for each line The line descriptor 
contains a profile which lists the frequency of words by length for die referenced line. 
This profile is the primary key for [he sort. Text comparisons only come Into play 
when the profiles are identical. 

To reduce the main sort effort, lines arc pre-sorted into groups which share the same 
longest word length. 

Each group is then sorted with heap sort, where the first phase (of inserting the line 
into a heap) is combined w ith making a copy of the line of text into a temporary prc 
sorted text, i.e. by line group. The second phase of the heap sort is then combined 
with copying the result back to the external text array, in the final order. 

Optimizations 


Memory accesses arc minimized by copying the text just once to temporary storage 
and back, as part of the sorting opration. 

The sorting itself is conducted with short line descriptors, based on bit-packed 
profiles. In most cases, a line descriptor will be 16 or 20 bytes Jong. 

The number of comparisons is reduced (further economizing on memory access) by 
using a combination of distribution sort (by line group ) and heap sort within each line 
group segment. Null and null-word lines remain in the original order anti are already 
sorted by the distribution sort. 

Most functions are written as inlincd, hut the compiler w ill not necessarily inline 
them, using its own "smart "ness. This is not necessarily optimal. 1 have forced it not to 
inline PopO and CompTextQ. This aJJuws the compiler then to inline oilier function, 
reducing the number of function calls overall. 

Assumptions 


{ 

// this simple intrinsic is just what Lhe job needs 
return 32 - _cntlzw(x); 

r 

// platform independent methtaJ: 
int n—0; 

white(x) ( x »= 1; ti++;j 
return n; 

7 

1 

// Private version of the table from etype, to include a code for End Of Line (kEGL) 
Static struct CharType f 
uchar T[256): 

CharType0 

{ 

for {long c=0 ; c(256;C++) 

T[c]=(lsalnum[c))?kAlnumTvpe:kWhiteTvpe: 

T[kEOL]-kEOLtype j 

] 

1 gCharType: 


struct LineDescriptor 

// A lineDescriptor characterises one line of text, 

// containing all information needed for efficient sorting 

struct LineDescriptor: 

typedef LineDescriptor* LineDescriptorPtr; 
struct LineDescriptor ( 

uchar * text Ref: // pointer to start of line in copy of text 

ul o n g 1 i neL e ngt b: // number of chars of this i ine 

ushort longestWordLength: // length of the longest word in this line 
ushort profile Len gth; // n umber of longs in profile 

1 ong p r o f i 1 e [ i ] ; // packed, numbe r of words per !e ngth 


TextToSort should end with a Mac new line character (0x0d) r Axiy text beyond the last 
newline character will not be sorted 

No assumptions arc made for limits except that the longest word must be less than 
128 characters long. Lines may lx 1 of any length and contain any number of words 

7 

//include (stdlib.h) 

//include (string.h> 

//include <ctype*h> 

//include ''LongestWordSort. h 1 * 

//define MAXLENGTH 127 // no word longer than MAXLENGTH chars is expected 

typedef unsigned char uchar: 
typedef unsigned short ushort: 
typedef unsigned long ulong: 

enum f 

kMaxLenfeth=MAXLENGTH, 
kAr r ay S i z e=1+MAXLMGTH, 
kEOL==OxOd< 
kAlnumType=0, 
kWhiteType=!, 
kE0Ltype=2 * 
kCaseSensitive=OxFF, 
kNoCase=QxDF, 
kSignEit=Ox800000DD 

h 

static uchar kCas eMask[2] = IkNoCase.kCaseSensitiveI: 
static ulong gCaseMask; 
static ulong gDescending: 

inline long Max(long a,long b) 

// .Algebraic method of selecting greater of two longs, avoids branch stalls 

E 

long D (a-b.) )) 31: 

long notD = -D; 

return [b & D) | (a & notD): 


Bits Needed 

inline long EitsNeeded(ulong x) 

// Returns number of bits needed to encode range 0 to x 


ulong LineLengtht) const {return lineLength;! 

long Init(uchar* lineStart*ulong lineLen,ulong longest, 
ulong lengthDist[],uchar fleldVidth[]) 
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800-231 -5920 800-757-9003 (Fax) 
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The products you need, with the prices 
and service you deserve... guaranteed. 


Power Tools for Programmers! 





Installer Maker 6.5 I OK 


CodeWarrior Pro 5 


CodeWarrior Professional 5 put everything you need for 
software development at your fingertips: project management 
tools, text and resource editors, source and class browsers, 
compilers, linkers, assemblers, and debugger Release 5 
such features as RAD for Java, faster compile times, local and 
remote application debugging, IDE extensibility options and 
even tighter C/C+ + compliance. Additionally, you can create 
applications for Windows 95/98/NT and Mac OS 8 x and Mac 
05 X from either host platform, (available in versions hosted on 
Mac or Windows). 


Spotlight 


Whether you 1 re a developer of high-end, complex applications, 
simpler utilities, shareware/freeware, an IS manager or an ISP 
who needs to distribute files quickly and easily, the new 
InstalLerMaker is the complete installation solution for you. 
Utilizing the power of the new Stufflt Engine, InstailerMaker 
creates installers faster and smaller than ever, decreasing 
download time off servers and reducing the number of disks 
needed to distribute installers. These time and cost savings go 
straight to your bottom line! 


VOODOO Server 


Future BASIC 3 


Resorcerer 2.2 


Resorcerer is the only supported general-purpose resource editor 
for Macintosh. Relied upon by thousands of Mac developers. 
Resorcerer features a wealth of powerful yet easy-ti>use toots for 
easier, fester, and safer editing of Macintosh data files and 
resources. Whether you have to parse a picture, debug a data fork, 
design and try out Balloon Help, create a scripting dictionary, create 
anti-aliased icons, design and edit a custom resource with 40,000 
fields in it, create C source code to run a dialog, or arty of hundreds 
of other re source-re I a ted tasks. Resorcerer's magic will quickly save 
you time and mone: 


NEW! 


VOODOO Server is a version control system for software 
developers using Metrowerks CodeWarrior under Mac OS. 
VOODOO Server and the corresponding VOODOO clients (the 
included CodeWarrior VCS plug-ln and the VOODOO Admin 
application] are designed to offer reliable and robust version 
control features while minimizing the administrative overhead 
that usually accompanies version control. If you're a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 


One or the most riexmie ano powerful development 
environments on the Macintosh today! Easily create programs 
with the visual program editor, drop Into the BASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly with the Macintosh toolbox. The 
only BASIC compiler on the market that gives you 100% access 
to all of the power of the Macintosh toolbox! 


$219 


Spotlight is the first Macintosh "Automatic Debugger", It can 
automatically locate run time errors in your code and display 
the offending source code line. Unlike similar tools on other 
platforms Spotlight is easy to use. No source code changes 
are necessary for application debugging. Spotlight can 
automatically check for wild pointers, memory leaks, 
overwrites, underwrites, invalid dereferencing of handles, and 
even toolbox parameter validity checking ■ spotlight knows 
Macintosh verifying parameters to over 400 toolbox calls. 


and hundreds more! 



MkLinu! 


Tools Plus 


Page Charmer 2.0 

$139 


Scripter 2.0 

$179 


WebTen 

$349 










































PO Box 5200 * Westlake Village, CA • 91359-5200 • Voice: 800/MACDEV-1 (800/622-3381) 
Outside US/Canada: 805/494-9797 • Fax: 805/494-9798 * E-mail: orders@devdepot.com 


www.devdepot.com 


Master the Web! 


WebSTAR Server Suite 4.2 


WebSTAR Server Suite is a complete set of powerful and easy- 
to-use Internet servers for the Mac OS. Effortlessly serve web 
pages, host email accounts, publish databases, and share files - 
all with a single application on one Mad WebSTAR Server Suite 
Is perfect for Internet or Intranet serving, single or multiple 
sites, small I and large businesses - it's power and ease of use 
i saves any organization time and money, 



Monitor the bandwidth usage of up to Five different machines on your 
network! Do you need to upgrade your Webserver? How hard is your 
eMail server working? Are you getting all the bandwidth you're 
paying for? Not only can CyberGauge answer ail these questions, 
new features allow CyberGauge to eMail or page your network 
device becomes unresponsive r passes a threshold of usage you 
define - an essential first line of defense for earty detection of denial 
of service attacks and necessity for warning you and tracking quality 
Of ISPs that may have brown outs and shutdowns 




Funnel Web Pro 


NEwfi 


NetBarrier 


fFunne Web is the ultimate web analysis solution for 
: ;i professionals. Specifically designed for profiling web site usage 
_ ] and monitoring customer usage patterns, Funnel Web is ideal for 
! examining server performance and online effectiveness. Funnel 
lAfeb can analyze log file formats from any server, WebSTAR, 
WebTen, even Unix or NT hosted ervers. Discover the most 
popular pages on your site, track server loads & optimize server 
performance, profile visitors based on organization, domain 
liame. country, browser, etc. Funnel Web does it all! 





$329 


NetBarrier offers a Personal Firewall, Anti vandal protection, and 
Internet Filtering. Protect your machine From Intrusions by Internet 
or AppleTalk. Incorrect passwords and individual actions are 
logged, you are alerted to hostile actions, and intruders are easily 
isolated. Internet Filtering allows you to be sure that passwords, 
credit card numbers, and other sensitive information can never be 
exported from your computer - the content itself is filtered before 
any transfer! {Rated A mice by Macworld Magazine] 



...and great hardware solutions! 


IMiM 


2 USB PCI Card 


Add two USB ports to your older Macintosh. Connect up to 
127 devices to the Universal Serial Bus [USB] that is 
Apple's new standard for desktop connectivity USB mouse 
devices, keyboards, joysticks, game controllers, printers, 
scanners — connect them all to your current computer. 
Installs in minutesF 


Maesense 



Do you need A monitors and A keyboards for your A servers? 
With Dr. Bott Moni-Switcb you can connect a single Keyboard 
and monitor to up to 4 machines at once! A simple flick of a 
switch directs the video input and keyboard commands to the 
appropriate CPU! Available in USB and ADB model's, with 2 
or 4 machine support, and bundles with USB PCI cards so 
you can mix and match USB and ADB machines with the 
same MonhSwiteh! Great for programmers to do back 
ground compiles, ideal for server rooms overcrowded with 
monitors and keyboards! 


NEW! 


$ 129 . 



Full Size Keyboard Maesense Internet Sharing Router 


Just plug this keyboard into your Mac and start typing! The 
|,UKB-60O keyboard from Maesense is designed to get. you 
ping quickly and easily, without any hassle or compatibility 
orries. It Features two tone translucent design, colored to 
f match your favonte flavor of Macintosh. It offers soft touch 
with positive tactile feedback and build built in USB port on 
either side of the keyboard. Includes a 5' USB cable and is 
\ 100% Macintosh compatible, simply plug and play, as easy 
j Macintosh! 



Looking to get your whole office online without shelling out 
thousands of dollars? If so, the XRouter Internet Sharing 
Hub offers the perfect solution. This amazing Ethemet-to- 
Ethernet hub connects an entire network of up to 252 users 
to the Internet using only one ISP account and one Cable or 
DSL modem! 





























// Initializes the fields for one line. 

// Returns the length of the struct, which includes the variable-size profile 

I 

t ext Ref=1 ine Start; 

HneLsngth^lineLen; 
longestWordLength=longest; 

// Builds the line profile by packing the number of words, by length. 

// into a siring of 31 -bit values for efficient comparison Liter. 

1ong* prof=profile: 
ulong acc=0; 
ulong fill=0; 

for (long len=longest;len>0;-len) 

l 

long nuitifiits=fieldWidth[ien] ; 
long value = lengthDist [leu ]; 
fill+=nmnB±tS“ 
if (fill > 31) 

fill=nmnBits: 

*prof++=acc; 
acc=value; 

1 else 

l 

acc = value | (ace << numBits) : 

] 

lengthDist[len]=0; 

I 

*prof+f^acct 

profileLength=prof- profile; 

return (sizeof(LineDescripfor) sizeof(ulong)) + 

sizeof(ulong) * proflleLength; 

I 


Line Descriptor :1 sUssThan 

ulong IsLessThan(const LineDescrlptotfi other) const 
// Returns true if this line should be “before the other line (ascending) 

[ 

// Compare line profiles first: 

const long* A=profIle; 
const long* Brother.profile; 

1ong pL ength=p ro fi1eLe n gth; 

// there is always at least one profile word to compare 
long delta = (*A - *B); 
if (delta) 

return delta & kSignBit; 

while (-pLength) ( 
delta = *++A - *++B; 
if (delta) 

return delta & kSignBit; 

I 

// Both profiles are equal: must compare on the basis of text; 
delta=CompText(other); 
if (delta) 

return delta & kSignBit; 

// The text is exactly the same: 

// Compare on the basis of the original line order 

// But reverse if descending to compensate for reverse CopyBack 

return gDescending A ((textRef - nther.textRefI & 
kSignBit); 

1 

static long CompWorde(const uchar* wl„ 
const uchar* w2 T long len,long caseMask) 

// Simple string comparison, character bv character, case sensitive as required 

l 

for (long i=0;i<len;i++] 

I 

long cl- i 'wl++ & casellaak: 
long c2 =l *w2++ & caseriask; 
long delta=ci-c2; 
if (delta) return delta; 

J 

return 0: 

) 


LineDescriptor:: LocateNext 

static const uchar* LocateNext[const uchar* start,long length) 

// Returns the next word of the specified length 


ulong c=* start,len-0; 
const uchar* word=start; 
for (;;) 

t 

long eharType=gCharType,T[c]: 
c=*-H-start; 

if (char Type=kAlnumType) // Is alnum 

( 

if (len”=0) word=£tart-l; 

len++; 

) else 
1 

i f (len—1 ength) // lengths match ; found it 

break; 

If (charType=kEOLtype) // reached end of die line 
return 0; 
len=0: 

3 

1 

return word; 

I 

void Write(uchar* outText) const 

l 

// Note: memepy is faster than sirnepy or character by character copy. 

meicicpyC outText, textRef * lineLength); 

) 

long CompText(nonet LineDescriptor^ other) const; 

H 


LineDescriptor: : CompText 

long LineDescriptor:tCompText(const LineDescriptor^ other) 
const 

// Returns result of comparing the line as text, longest words first 

I 

for (long len-loiigestVordLength; len>G;len-) 

( 

const uchar* vl=textRef; 
const uchar* v2“other.textRef; 


if [0— (wl=LacateNext ( wl ,len))) 
break: // no word of this length found 

w2=other.LocateNext(w2,len): 

// if wl exists, w2 must exist 

long d=CompWords(wl ,vrifo len, gCaseMask); 

if (d) 

return (d); 
wl = wl+len[ 
w2 - w2tlen; 


return 0; 

1 


struct Segment 

//The priority queue (Heap) structure is used for sorting the line descriptors. 

// Sorting occurs in two phases: Insert0 and PopO 

//We build a separate heap for each HneGroup segment (which shares a common 
// longest word length). This reduces the size tif the individual heaps, resulting in 
// fewer comparisons overall 

struct Segment ( 

LineDescriptorPtr* heap Base; 

ulong heapSize; 
ulong maxHeapSize; 
uchar* nextLineDesc; 
ulong lineDescSize: 

//Just keep track of the line count, to prepare correct heap size 
void AddLine (HmaxHeapSize++; I 

ulong MemRequired(ulong profileLongs t ulong profileEits) 

\ 

// Returns the amount of memory required for lineDescs and their index (=heap) 

if (maxHeapSize=0) return 0: 

ulong profileSizeInLongs=profi1eLongs+(31+profileBits)/3 2 ; 
ulong profileBytes = 4*profileSizelnLongs; 
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lineDescSize= 

profileBytes + (sizeof(LineDescriptor) - sizeof(ulong)); 
return 

lineQescSize 1 tnaxHeapSize + //for linedcscs 

eizeaf(LineDescriptorFtr*) 1 (I+maxffeapSize) Jfht heap 

index 

I 

uchar* Init(uchar* memPool) 

\ 

if Grabs memory from the pool for IineDcscs and the heap; returns updated poof 

if (maatHeepSize/O) 

I 

nextLineDeac^nieinPooI; 

mEmPcinl += maxHeapSize * lineDescSize: 

heapBas€^(LirtaDescrxptorPtr - ) memFool: 

memPool += sizeof (LinaDeseriptorPtr*) * (I+maxHeapSize); 

return mentPool; 

I 

LineDescriptorFtr GetLineDescO 

//Walks the index memory to assign consecutive line Dose indices 

LineDescriptorPtr next^LineDescriptorPtr(nextLineDesc); 
nextLineDesc +* lineDescSize: 
return next: 

J 

void Insert(LineDescriptorFtr k) 

// Inserts one line, while main raining the heap property 

long i=++beapSize; 
long j=i»I; 

LinaDeseriptorPtr z: 

while (j && {k-)IsLessThan{*(z=heapBase[j])))) 

heapBase[i]“z: 

i=j: 

3-i»i; 

heapBase [i]-k; 

J 

uehar* CopyBack £uchar* lextToSort) 

// Pops one line off tile heap, and copies the referenced tine to the output. 

//When descending, lines are copied starring at the end of die output. 

// Returns the updated output text pointer, in preparation for the next copy 

if (0—heapSize) 
return textToSort; 

if (g|3 esc ending) 

uchar* endText“textToSart: 
do I 

LineDescriptorFtr textLine = Pop(); 
uchar* outText=endText - textLine->LineLength[); 
textLine->Write(autText); 
endText-outText; 

J while(heapSize): 
return endText; 

1 else 

I 

uchar* outText=textToSort; 
do i 

LineDescriptorPtr textLine=Pop(): 

textLine->Write(outText); 

outText+“textLine->LineLength £): 

I while(heapSize); 
return outText; 

) 

I 

LineDescriptorFtr Pop[); 


Segment:; Pop 

LineDescriptorFtr Segment: :PopO 

// The node at heaphase[11 has the lowest weight. 


// H is popped from the heap and returned, 

// The heap is adjusted to maintain the heap property 

\ 

LineDescriptorFtr rc=heapBase11]; 

LineDescriptorFtr k=heapBase[heapSize-] ; 
if [heapSize<=l] f 
heapBase[l]=k; 
return re; 

I 

long i=i. j”2: 
while (j<HieapSize) 

if ((j<heapSize) 

&& (heapBase[j+lj->IsLessThan('heapBase[j]))] 

j++; 

if (k->IsLessThan(* heapBase[j ])) 
break: 

heapBase[i]“heapBase[jj: 

I 

heapBase[l]=k: 
return ret 


struct Text 

struct Text f 

uchar* theText; 
ulong textSize; 
uchar* copyText; 
ulong gNumLInes; 
ulong gLongest; 

uchar* lineDescMemory: 

// highest number of words of length x in a line: 

ulong lengthDist[kArraySizel: 
along tempLengthDist[kArraySize]; 

// one segment of lineDescriptors for each passible lineGroup 

Segment segment[kArraySize]: 




Database application generation from AppMaker d-Base 
compatible engine; Faircorn n-iTee Plus c++ Interface with 
many added features; cross-pfalform graphing; cios*- 
platform report-writer ( XML, RTF, HTML output, Pow«rp|&nt 
interface, MFC ini efface easy-to-use API cross-platform 

Cross-Platform C++ 

from AppMakei d-Basa compatible angina. Faircorrt c-traa 

PP2MFC puts your 
PowerPlant 
applications on 
Windows - 

platform repofl-wiitar; XML, RTF. HTML output; PowerPlant 
interface. MFC interface, easy-to-use API; cross platform 
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if (len) 


// register the word 


// size t=num€hars) of each text segment by longestWorel line group' 
ulong segment Size [kAraty Size] : 

// start of each text segment by longestWond line group 
uchar* segmenfStart[kArraySize]; 

// width of profile fields in bits for each possible word length 

uchar fieldWidth[kArraySize]: 

Text (char *textToSort ( long numChars) : 
theText((uchar*)textToSort), 
textSize(numChars), 
copy!ext(new uchar[numChars]) 

t 

// Constructor analyzes icxl and computes text profile, prior to sorting. 

// Determines the division of the text into fine groups. 

raemset(lengthDist,0,sizeof[lengthDist} 

+ sizeof(tempLengthDist) 
i sizeof(segment) 

4 sizeof(segmentSize)}; 

AnalyzeO 1 

CotaputeFieldSizes (); 

1 i neDes cHemory=GetLineDeseMeiiiory () j 

1 

-TextO 

I 

delete [] lineDescMemory; 
delete [] copyText; 

1 

void Sort() 

// Does the actual sorting of the segments: 

l 

// Seans die text a second time while inserting lines in segments heaps 
// Ibis constitutes the first phase of sorting. 

Presort(): 

// Zero-word lines will be in die original order in line group I), 

//They can just lx: copied en bloc, to the from or hack end of the output, 
uchar* dest-thaText; 
if (gDescending) 

[ 

dest +- textSize-segtnantSize [Q] : 
ntemcpy(dest H copyTexl h segmentSiza [Q] ] : 

3 else 

I 

memc-py(dezt * copyText„ segmentSize[0]) t 
dest 4^ segmentSize[0]: 

1 

//The remaining lines are popped from each segment heap, 

// starling wtth the linegfoup with die shortest longest words 
// This completes the second phase of sorting 

for (long len=l:len< = gLongest:len4+) 

[ 

dest-segrcent[len].CopyBack(dest): 

3 

I 

void Analyze0: 
void CoraputeFieldSizesU : 
uchar * GetLineDescMemory(); 
void Presort(); 

n 


Text:: Analyze 

void Text:: Ana .ly z e {J 

// Scans the original text anti collects statistics such as 

// - the number of lines 

// - the number of words hi length 

// - the size of each line group (lines with the same max-length) 

// - die longest word in the w hole text 

//The loop in tills routine relies on finding a OxOd character at text end. 

I 

ulong len-0,longer t=0,nuraLines^O: 

ulong globalLongest=Q; 

uchar* text^theText: 

ulong c=*tExt; 

uchar* lineStart=text; 

ulong numChars=t extSize: 

for {;;) 

I 

long charType=gCharType. T [ c ]: 
c^*++text; 

if (cha rTy pe—k A In uinTy pe) len++; // part of a word 
else 


1 

L 

tempLengthDist[len]++: 
longest=Max(longest.len): 
len=G: 

1 

if (charTy pe=kE0Lty pe) // register the line 

i 

for (long 1=0:1 ^longest* 1++) 

1 

if (lengthDist [1] < tempLengthDist [1]] 
lengthDist[11 = tempLengthDist[1]: 
tempLengthDist[1]”0: 

I 

segment [longest] .AddLineO; 

globaLLongest-Max(globallongest* longest); 

ulong lineLength=text-lineStart; 

segmentSize[longest]+=1ineLength; 

numChars -= lineLength; 

numLines++: 

if (numChars <= 0) 
b reak; 
longest=Q; 
lineStart=text: 

) 

1 

I 

gNumLines = numLines: 
gLongest = globalLongest: 

I 


Text::ComputeFiddSizes 

void Text:iComputeFieldSizes() 

// Computes the minimum field widths for profiles, for each word length 
// also devides the text copy into segments, one per line group 
t 

uchar* startleopyText: 

for (long len“0:len<=gLongest;len4+) 

l 

fieldWidth[len] = BitsWeeded(lengthDist[len]); 
segmentStart[len]=start; 
start+=segmentSize[len]; 

I 

r 


Text::(ietlineDescMemory 

Uchar* Text::GetLineDescMemory() 

//Allocates the memory required for the variable size line descriptors 
if and sets up the line Group segments. 

if Note: In the Interest of not fragmenting the memory heap unnecesssarily, 
ff this memory is allocated as a single chunk, and then divided 
ff out among the segments for line descriptors and index arrays. 

( 

ulong memRequired=0; 

ulong profileBits-0.profileLongsH): 
for (long len=l:len<=gLongest;len++) 
l 

long fWidth=fieldWidth[len]: 
if CfWldtb) 
t 

ff accumulate total bits to cover fields up to length len 

profileBita 4^ fWidth; 
if (proFileBlts > 31) 

I 

pmfileLongs+4; 
p rofilfcSit s“fWidt h: 


// if segment|len] is not empty reserve memory for it 
memRaquired += 

segment[len].MemRequired(profileLongs P profileBits): 

\ 

I 

//Allocate all required memory .. 

uchar* allocaled-new uchar[memRequired]: 
memset(allocated * 0,memRequired )\ 

H ... and divide it among active segments 

uchar* memFool = allocated; 
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for [long len=i ;len<=gLongest ilerrH-) 
memPool”3eminent [ien] . Init (memPool) ; 


return allocated; 
I 


Text:: Presort 

void Text::Presort0 

// Second scan of the text: 

// assigns and initializes a line descriptor for each line, 

// and inserts it in the selected segment 

[ 

uchar* text^theText; 
along 1*11=0, Ion gee t=0; 

memset[tempLengthDist+1♦G.gLongest^sizeofCuloagJ}; 

uchar* lineStart“text: 

ulong c=*text; 

long numLines^gNumLines; 

for (:;) 

I 

long charType=gCharType,T[c]; 
c“*++text: 

if (charType—kMmimType) le&++; 

else 

I 

if (1 en) // register the word 

! 

tempLengthDist[len]++; 
longsst=Max(longest.ien); 
len=0; 

] 

if (charType=kEOLtype) //register die line 

I 

-numlines; 

ulong 1ineLength=text-linestart; 

uchar* copyDest=@egmentStart[longest]; 
meanepy (copyDest, lineStart. lineLength) : 
segmentStart[longest] = copyOest+lineLength; 
lineStart=text; 

if [longest] // mate a new line descriptor 

I 

LineDescriptorFtr lineDesc ” 
segment [longest].GelLineBesc(): 

// note side effect: Init dears tetmpiengihDLst 
lineDesc(copyBest *lineLength.longest. 
tempLengthMst. field Width): 

segment[longest],Insert(lineDesc): 

longest=0: 

I // else, no need to do anything (no words in line) 
if (numLines<=0) 
break; 


1 


LongestWordSort 

void LongestWordSort( 

char * t ext To So r 1 , p the text to be sorted */ 

long numChars. P the length of die text in bytes V 

Bool ean d esc ending, P sort in descend! ng order if true 7 
Boolean case Sensitive /* sort is case sensitive if true 7 
) I 

//Just to be sure, let's ignore all text beyond the last CR 

while (numChars && [kEOL != textToSdrt[numChars-1])5 
numChars—! 

if [numCha rs—0} return; // quit if there is no text to sort 

// Make sort parameters global 

gDescending=[descending)?kSign£it:Q: 
gCaeeMask-kCaseMask[caseSensi tive] ; 

// Initialize 

Text * T“new Text[textToSo rt* numChars); 

// and sort: 

T->SortO: 
delete T; 
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Once you have 

your film, 

all you need are the right 

connections. 


Don't keep the world waiting for your master¬ 
piece. Transfer it out of obscurity and onto your 
computer with the Belkin USB VideoBus II 
for Macintosh 0 computers, VideoBus II lets 
you zip your unforgettable images anywhere, quicker than 
you can say SumJonce, Now you can capture and edit live video 
on your computer—then put your creation on CD, DVD, the 
Web, or in e-mail for all the world to adore. All you need is 
the VideoBus II to connect your Mac to any camcorder 
Capturing your images is just the beginning, VideoBus II for 
Macintosh computers comes with Strata's VideoShop 4.5, the 
Impressive editing package for creative professionals. OBB 
Features such as its Motion Path Editor and unlimited Ewgji 
tracks for powerful compositing will have you designing 
and producing professional quality movies on your computer 
in no time. Create incredible presentations, videos and e-mails 
that really open doors. 

So capture a VideoBus II connection, and let 
your images dazzle them in the light of day. 

WdedSus II™ 
Part U: F5U20B-mC 




bflHdn.fiOfn 

Belkin Components - 310.898.1100 * Fax 310,898.1111 * Compton, CA 
■ Atlanta, GA ■ United Kingdom * Hoi fan d 

i£j 2000 Belkin Componenls. All rightH recurved. Alt trade frames are registered trademarks 
of respective manufacturers listed Z0AO3?7/MCH 









OPERATING 

SYSTEMS 


By John C. Welch 
Edited by Ilene M. Hoffman 


Mac OS X Public Beta 


An Administrator’s Review 


Welcome 

Before I review Mac OS X, the 
next generation of operating system 
from Apple Computer, Inc., Td like to 
emphasize one point: It’s A Beta. 
The fact that it's called a public beta 
should make that emphasis 
unnecessary, but some comments I've 
read on die Internet and mailing lists 
makes me think thaL the emphasis is 
needed. This is a review of the Mac 
OS X Public Beta, which means that a 
lot of what 1 dislike or like may 
change, so don't think that anything 1 
mention will be included in the final 
product. Finally, I’ve only had the 
public beta for about a week and a 
half at tills writing, so there are a tot 
of items 1 may not cover yet. Okay, 
enough warning, on to die Beta! 

Installation 

The first place to start is die 
installation of Mac OS X Public Beta. 1 
have been running the Public Beta on 
a Power Book G3 Series, Bronze 
Keyboard, 1999* It has 192MB of 
RAM, and a third-party 18GB hard 
disk with two partitions, the Beta 
being on the second partition, which 
is about 3GB in size. I have not been 
using Classic Compatibility 
Environment for two reasons: First of 
all, l have certain extensions and 
configurations that aren't compatible 


with Classic that I need to use in my daily work. Secondly, 
I wanted to get a feel for OS X as its own operating 
system, without falling back on Classic as a safety net. 

After reading the Read Me files, installation notes, 
and other information available on Apple’s website 
(http;//www.apple,com/osx/), I booted from the Beta CD, 
and started the install process. When you boot from the 
CD, you boot into the OS X install program. Here is one 
of my first beta gripes, as a network administrator, one 
of the tilings [ really like about die Mac OS over 


Note: Always read the Read Me files and 
installation notes. It 1 see many problems reported 
that were clearly dealt with in the Read Me files, or 
installation guide. Besides, you never know when 
you'll get something out of it, IBM. for example, in 
their 45 - page readme for the OS/2 2.1,1 update, 
included on the next to last page, the instructions 
for finding, and installing Mah-fongg. No where 
else was this information found. It was kind of a 
nice reward for diligence.) 


Windows NT/2000, is that when 1 boot from a CD, 1 
boot into the Mac OS, with basic networking capability 
enabled, can boot from the CD, get onto my network, 
and have full access to utilities, install points, etc. 
Currently the Mac OS X Public Beta CD only boots into 
the installer, which is annoying, and hopefully is not the 
future design of the final product. Aside from that, the 
install is fairly uneventful. 

You pick the drive to install onto, agree to the 
license agreement, and go. There's no options for the 
install, so custom installs don’t apply, yet. On a freshly 
formatted partition on my PowerBook, the install took 


John Welch <jwelch@aer.com> is the Mac and PC Administrator for AER Inc., a weather and atmospheric science company 
in Cambridge, Mass. He has over fifteen years of experience at making computers work. His specialties are figuring out ways 
to make the Mac do what nobody thinks it can. and showing that the Mac is the superior administrative platform. 
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about 15 minutes. Once the installer is done, the Setup 
Assistant fires up, and walks you through entering the 
base information to set up the Mac, It’s pretty much the 
same as the Mac OS 9 Setup Assistant, except for 
entering an administrator username and password. 
This password is also used as the password for Toot' 
or the Unix super user ID 

This brings us to another difference in OS X, the 
concept of the super user. The super user, or root, is 
the Unix equivalent of god on that machine. If you can 
log in as root, there is nothing you cannot do on a 
Unix machine. Literally, nothing. Do you want to 
rebuild the kernel? Root can. Do you want to delete 
every file in \etc, which is the directory that holds all 
of your configuration files? Root can. The point here is 
that root is a very powerful and very dangerous, so 
you want to be very careful about that user id. You 
should never log in as root unless you have a specific 
need, and then you should log out as soon as possible. 

The Interface 

Once the setup assistant is done, Mac OS X 
reboots, and you are presented with the login screen. 
Once you log in, using the user ID and password you 
gave the setup assistant you are on the Mac OS X 
desktop, and ready to roll. One of the first eye- 
catchers, or at least mine, wasn't the Dock, but rather 
the lack of my hard drives on the desktop. There are a 
number of arguments for and against this, but for me, 
the two seconds it takes me to put an alias to the drive 
on the desktop renders it somewhat moot. Creating an 
alias requires the exploration of the new Finder. 

The Finder 

In Mac OS 9 the Desktop and Finder were 
interchangeable words; but in Mac OS X, the Finder is 
part of the Desktop application. The Finder, as in 
previous systems handles file-system functions. 
Visually, in the Finder window you see a number of 
buttons, similar to Sherlock 2, that are shortcuts to 
various places on your Mac OS X drive. These 
represent folders you would need to go regularly, such 
as Favorites, Applications, Documents, and a new one, 
Computer, as shown below. If you don't like the 
buttons, then §§(command)-B toggles them on and off. 
Also, if you have placed a folder in the Dock. 36- 
clicking it opens it with the buttons hidden. Both views 
are shown below. 



Professional Macintosh & Internet Development 


Always Thinking’s professional developers will 
help you meet your Macintosh and Internet 
deadlines! So if you’re... 

• on a tight deadline and need additional talent 

• losing valuable development time debugging 

• having trouble finding good developers 

Always Thinking’s team of experienced 
programmers will provide you with a timely and 
affordable solution. 

We deliver more than code — a complete project. 
Our software engineers work with you to: 

• Create clear, solid project specifications 

• Design and develop your application or web site 
•Tune and optimize your software’s performance 
•Thoroughly test your application or site 

• Completely document your project 

• Provide training to your team 


Commercial Product Development 


Do you have an exciting idea for an application? 
Turn to Always Thinking to make it a reality. We 
have firsthand experience developing and shipping 
award-winning commercial applications for our 
clients and our own Thinking Home, a 2000 
Apple Design Award winner. 


Web Site Design & Development 


Get a sound e-commerce system tailored for both 
your immediate needs and long-term growth. Our 
engineers can develop the Internet applications to 
transform your company into an e-business. 

Successful web sites are more than graphics and 
code. We have the Internet marketing know-how to 
ensure your site is an effective business tool. 

Realize substantial savings by moving to online 
pre-sales information, ordering and support. 


Tell us about your project, toll-free 

( 800 ) 252-6479 

(703) 478-0181 x103 

Always Thinking, Inc. 
27 James Byrnes Street 
H Beaufort, SC 29902 

www-alwaysth in king.com sales @ a 1 waysthi nki ng.com 
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The Finder at Computer Level with the Toolbar 
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fvjf Show removable disks (for example, CDs) 
on the Desktop 
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The Finder at Computer Level with the Toolbar 
Hidden 

Computer is the root level of the system, and 
should be thought of as looking at the computer from 
bottom of the hierarchy, in that everything is above 
you. This level shows you all your disks, along with a 
new entry. Network, which we cover later. This view 
of the drives has caused some consternation, as 
previously, these items lived on your desktop. Well, 
the reason for it, although it doesn’t apply in a 
standalone machine situation, is if you are accessing 
machines on a network, and you log into that machine, 
you are going to see a view that is a container for all 
the accessible shared drives. This network-centric view 
is essentially what Computer is giving you. The 
advantage to this view is that if you are in a heavy 
networking environment, you don’t have to change 
view modes between your local Mae and Macs on the 
network, The disadvantage to this is if you are in a 
standalone situation, you could care less about the 
network view. Fortunately, in the Desktop and Dock 
preferences, you can set, your removable media to 
automatically show on the Desktop, as shown below. 


Preference panel for displaying removable media on the Desktop 


This is nicer, and less jarring to those of us not 
used to the NeXT way of looking at things. I think 
Apple would do well to add a “Show Internal Disks on 
Desktop” option here though. 

Another of the changes in the Finder is the 
Browser view, shown here. 



Browser view in the Tinder showing path to the folder with the 
Fire application 


The Browser view is a side-scrolling, multi-paned 
window that shows you your current location, on 
either the local hard drives, or the network. If you 
have a folder selected, it shows you all the items in 
that folder in the rightmost pane. If you have a 
document selected, it attempts to show you a preview 
of the document, along with die standard Gel Info 
information. If you have an application selected, you 
get the generic Get Info details on the application. 
Although a little jarring at first, ! have actually grown 
rather fond of the Browser view, it is fast, easy to use, 
and the ability to backtrack that easily through what 
can be many, many layers of folders is more than a 
little sweet. (To all the NeXTies — yes, you told me 
so + ) I also find that some of the other modifications to 
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You think the Internet is safe. 

Think again... 



NetBarrier. The first Internet 
security solution for Macintosh. 


• TIhiIES 

- 1 internet security solution 



All Macs connected to the internet (dialup. 
DSL, cable-modem) are exposed lo hackers. 
Whether you are a home user or a 
professional user, your data interests them. 
Hull's why you need a security solution that 
only NetBarrier can provide. 

Personal Firewall 

NetBarrier protects and monitors sill 
incoming and outgoing data. A customized 
mode allows you to create your own 
defense rules* thereby offering the most 
secure level of protection* 


Antivandal 

NetBarrier blocks all attempts to break 
into your Mac, detects wrong passwords 
and logs vandal attacks for complete 
protection. Moreover, it has an alarm to 
inform you of every intrusion attempt. 

Internet filter 

NetBarrier analyzes data as it leaves your 
computer and prevents unauthorized 
exporting of private information such as 
credit card numbers, passwords, sensitive 
data and more.*. 


@ DEPOT 


www.intego.com 
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intego 


A*** 


< htt p ://w ww. devdepot. com > 

Toll Free: 877-DEPOT-NOW 
Outside U.S./Canada: 805/494-9797 
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the Finder windows, while jarring in some ways, make 
accessing die full features of the Finder windows more 
intuitive. The new drop-down list that shows your 
location in the folder hierarchy, has always been 
available via command-clicking the title bar, but this 
always struck me as too useful a feature to be hidden 
away as some power-user trick. Users need to be able 
to see where they are regardless of the current Finder 
view, so placing this feature out in the open is good. 1 
also like the addition of a Back button, which makes 
this feature obvious without having to know oddball 
key combinations like SELL I know that experienced 
Mac users are saying, “But that's so intuitive already.” 
Well, for the true novice it isn't, and making it more 
obvious and intuitive does not distract from the power 
of the Desktop. It just makes it available to more 
people, and quicker. 

Dock & Desktop Preferences^ 

_ f' Dock ^PeskfopY FTrider ^ __ 


When you open a folder from a Finder window, 
show the folder's contents; 

© in the same window 
Q in a new window 

To fevers* your choice for a paiticuhr folder, hofd down the 
Option key while you open that toteler. 


Preferences Setting for how the Finder pops windows 


i also like the choice between having only one 
Finder window as you navigate, or the more traditional 
multiple windows. As someone who lives with their 
finger firmly planted on the Option Key, Fm very glad 
that Apple gave me this choice. There are, of course, 
some issues with the new Finder window. I would 
prefer the title bar to tell me the directory name, 
instead of the application name. 1 know Fm in the 
Finder, but what directory am I in? Keyboard 
navigation is inconsistent, for example, 9E-Y is gone, 
so you have to revert to using SE-E for eject to 
dismount network drives or removable media. That's a 
little strange, as I’m not ejecting the network drive, Cal 
least l better not be), fm removing it from my machine 
for a while, I also would like the browser view to scroll 
as I drag items back from the current location, and 
better yet, forward to new locations, which would 
make up for the missing spring loaded folders, I find 
that most of these issues have the feel of beta bugs, 
more than eliminated features, so Fm not too worried. 


The Desktop 

The next set of changes is in the Mac OS X Desktop. 
At first glance there seem to be a lot of changes, but, in 
fact, I couldn't find that many actual changes. IF you 
have been using OS 9’s Multiple Users feature, 
Macintosh Manager, or NetBoot, much of the way 05 
X's desktop works will be familiar. If you have been 
using your Mac in a single user mode, then some of OS 
X's desktop will seem a bit odd. First of all, each user 
has their own Desktop Folder. This is so that you don’t 
have situations where someone accidentally deletes or 
rearranges your desktop. They can't get to it unless you 
allow them access. This is annoying for the single user, 
, although when we look at the system preferences, the 
workaround will be clear. For the networked, business, 
or home user with the entire family using the same 
computer, this is a good feature, and is by far better 
implemented than in the current Mac OS's versions. This 
is not a surprise, as Unix has always supported multiple 
users this way, and OS X carries Lhis UNIX-type support 
into the Mac OS. Also, in the current beta, you can't 
rename drives. Although there are pathname issues for 
this from the Unix perspective, this is a behavior that 
Mac users are used to being able to perform, and it 
should carry over into Mac OS X, If there is a reason for 
it not to be there, then it should be clearly articulated as 
soon as possible. 

Another obvious change is [he location of the Trash 
icon. It’s no longer on the desktop, but rather on the 
Dock. This is a different location, but the functionality is 
still the same. You drag files to it, open it up to remove 
things, unmount media by dragging it to the trash. 3E- 
backspace places things in the Trash, and shift-8E- 
back.space empties the Trash. By placing the Trash on the 
Dock, il can't get hidden or lost behind other windows, 
which is good for new users. Considering the time I've 
wasted over the years working with cluttered desktops, 
and typing t-r-a as fast as I could, it’s a good move for 
experienced users as well. 

The icon size on the desktop is independent of the 
screen resolution and that is a feature that is sure to 
be greeted with joy by the vision impaired everywhere, 
including yours truly. 1 like the fact that I can have 
room for the way I work, and still be able to resize my 
icons to where I can see them without having to drop 
the resolution. 
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Dock & Desktop Preferences 

f Pock fmrnsxf^ mu f Vinter \ 


icon size: 

t?- 

Small Large 

Icon arrangement: 

© None 

O Always snap to grid 


Desktop Picture: 



f Remove Picture ^ 


Desktop Preferences showing Icon Size settings and Desktop 
Picture Settings 


There are some interface issues with the Desktop 
that seem more like beta bugs than anything else. Auto 
sorting by name is not enabled, and the Desktop 
doesn’t refresh its contents as fast as it should, 
especially if you use the command line to add things 
to the Desktop. You cannot have slashes in the names 
of files, which is a limitation of OS X, not HFS+, 1 
understand that Unix uses slashes as directory 
delimiters, but this is not Unix, it’s based on Unix, and 
this is a restriction that may cause problems, (Note: 
There were also applications in previous Mac OS 
versions that had trouble finding files when slashes 
were used in filenames,) On the other hand, you also 
now get 255-character filenames, so the news isn’t all 
bad. Finally, the system font and font size cannot be 
changed, l understand that Lhe font size can be 
changed by scaling the icon size, but some of us want 


tiny icons and big fonts, or vice-versa. We also want a 
font that isn’t Lucida Grande* These are annoying 
problems, but fixable, and l imagine they will be fixed 
in the release version of Mac 05 X, 

The Dock 

On to the most controversial pail of the new OS, the 
Dock, This is an amazingly polarizing application, and yet, 
like much of OS X, it really does grow on you. I think much 
of the problem is what it's replacing: the Apple Menu, the 
Applications Menu, the Menu Bar clock. 'Hie Dock also 
contributes to the loss of tabbed folders, which for some is 
more traumatic than others. Now, lets take a look at the 
Dock, or at least my dock after login 

The Dock is a bit smaller here than on my normal 
screen, but, even on my FowerBook’s display, there Is 
a lot of feedback here that you don't get by default in 
Mac OS 9- First, I know exactly what applications are 
running, in this case, from left to right: Finder, Stickles, 
Console, Classic Menu, wClock, and Grab. Classic 
Menu is an Apple Menu replacement for OS X, and 
wClock gives me a menu bar clock, and calendar as 
well. (Note, the Public Beta represents one of the 
biggest shareware and utility goldmines for Mac 
developers, and 1 am pleased to say that there is a 
wealth of items out there already.) I also have a 
number of applications handy that l use frequently. 
The four items on the left are the Trash, the What’s 
New Help file, the link to the OS X feedback page at 
Apple, and a link to my Applications folder. In 
addition, although I couldn't get screen grabs of this, 
3§-Tab cycles through the open applications, and pops 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Weil, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- View-Controller 

AppMaker's generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code” 
to implement your design. 


Scriptable Applications 

AppMaker generates the 'aete' resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 
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their names up so I can see which one is selected. 
Similar to the Desktop icon size, the Dock icon size 
can he set independently of screen resolutions, as 
shown below, 

. .. 

f &m' f paWop Y Disks f < rnder ; 


Dock size. 


0 Magnification: 

Smatl 


Q Auto hide and show 


§J Animate opening applications 


Dock Preferences Panel 

I have the magnification, and hide and show 
features turned off, and the opening animation turned 
on. Now one thing that you may notice that is not in 
my Dock is the clock. I tried storing it in the Dock, hut 
it was too small. I tried the floating option, but it was 
in the way all the time, plus the icon running in the 
Dock, took up space in two places, So i now use 
wClock, which gives me a menu liar dock, and in 
conjunction with Classic Menu, makes my menu bar 
look quite familiar. The dock on the menu bar is very 
handy, and an option to have it there, Una ting, nr in 
the Dock would he appreciated by many users. 

Menu Bar with wClock and Classic Menu running. 

There is another feature to the Dock which has 
only been hinted at, but in fact is a major plus , and 
that is the ability of the Dock icons to display live data. 
Aside from the endless demonstrations of QuickTime 
movies in the Dock, there are some other nice 
applications that make good use of it. 



Mail Application Dock Icon showing 
u n rea d m a i / sy m bol 

The Mail application uses the Dock icon to indicate 
you have unread mail in your inbox. Very nice, and 
handy if you don’t want to have your Mail window 


always open or maximized. Another application that 
makes use of this ability is the CPU Meter application. If 
you minimize both windows, the Dock icons update the 
usage graphs in real time, giving you a miniature, yet live 
display of how hard you are hitting your system. 



Dock showing live CPU Meter icons 

So while the Dock may not be the end all 
application f it is a lot more capable than people give 
it credit for. I hope that application developers take 
advantage of its abilities. 

Setting Up OS X 

Enough of the basic user interface, let's take a look 
at how you set your system up. Almost all system 
settings are accessed through the System Preferences 
application. After about a week of exploring Mac OS X, 
1 found out that Apple has done some pretty neat things. 
First off, the System Preferences are doing a lot of the 
low level Unix configuration file editing. For example, as 
you go through and set your network preferences in the 
Network control panel, you also alter the Netlnfo 
settings. Netlnfo is the way that NeXT networks kept 
track of machines, users, accounts, printers, and access 
rights, plus everything else. It is analogous to Novell’s 
Directory, or LDAP (Lightweight Directory Access 
Protocol), and is administered via the Netlnfo manager 
application. However, as we will see later, this is not a 
very intuitive application, and setting the wrong thing 
can hurt your configuration, and prevent your Mac from 
booting. Netlnfo also holds information for files like 
hostconfig, which is where the BSD Unix layer gets its 
information for things like host names, and IP addresses. 
From what I can see. System Preferences modifies 
Netlnfo, which modifies the configuration files. This may 
not he totally correct, but not having to use a terminal 
and FMACS, or worse yet. vf to set up your Unix 
settings; indeed, never having to even know where 
hostconfig lives, is a sign that Apple has put a lot of 
work into taking the Unix fears out of Mac OS X. 

System Preferences 

Now let’s take a look at a few of the features in 
System Preferences. The application reminds me of the 
Mac System 6 control panel, where one application 
held all your system settings. Although the OS X 
System Preferences application is a nicer version, it is 
still a single, coherent place for system, not 
application-specific settings, "[’he full view of the app is 
shown next. 
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The next control panel of interest to network 
administrators is the Internet settings panel. This 
illustrates Apple’s attempt to bring the functionality of 
Internet Con fig into Mac OS X. 
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For the most part, these look familiar, so we won’t 
take a look at all of them, but 1 will cover the settings 
of interest to network administrators. 

The first one is the Date & Time control panel: 



Web settings of the Internet control panel 
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DateS Time } Time lane ‘f Network Time 


Network Time Synchronization on 


Pick Stop to turn off Network Tlmt Synchronization. 

Network Time Setver_ 

Configure ' 

® ManubMy 

NTP Server: 




Pick live Pock to m*kt Ganges. 


Date & Time Control Panel Network Time tab 


The other reason I am highlighting the Internet 
preferences panel is to show that: 

1. In the Web tab you have the same flexibility in 
selecting your default web browser in Mac OS X as you 
do in OS 9. 

2. Voit can select where to Download Files To, so 
that with the multi-user capabilities of OS X, I, and 
anyone else who uses my Power Book under OS X can 
have our web browser download to the desktop, yet 
not interfere with anyone else’s desktop. 

This is nothing completely new, but the fact that it is 
an integrated feature ol the OS, instead of a bolted-on 
kludge will result in a smoother user experience. Do 
expect changes here though, as Mac OS X uses the word 
“E-mail" even though their own style guide uses “email." 

S P 1 & 0 H 

shew All Monitor; Sound Network Startup pj$k 


The first two tabs, Date <& Time and Time Zone, 
have Lhe same functionality as the Mac OS 9 versions 
The Network Time tab is interesting though. It gives 
you the ability to either manually enter a network time 
server’s domain name or IP address* or you can select 
From Netlnfo, and let NetTnfo handle where on your 
network your Mac gets its time information from. This 
feature is a boon to anyone trying to change this 
setting on a network with a few hundred MacsJ hope 
that Apple allows for Netlnfo to integrate with other 
directory services too, so that this type of 
administrative tool is not limited to Netlnfo. While an 
excellent way to manage a network, Netlnfo is hardly 
the one of the most common tools. 


Login Items Login Window 


D Automat itaHv tog m 

Name: 

Password: ' W* ^ 

rj Disable He start and ihut Down buttons 

CHdt thfl lock to make changes. 


Login control panel showing the 
Login Window Settings 


42 


Mac OS X Public Beta 


MacTech • November 2000 




























































Show All 


m 

MonSlort 


F)tiCftnCCi - Ulfiifl 



Sountf Network Sunup D^k 


I 


Login hemT^ Logm Window 


These items ivil! open automatically when you log lit: 
Hide Item Ithsd 

Application 
Application 
Application 
Application 


H ; Stick im 

$ MR Console 
Q c. Classic Menu 
□ 4*wCI«* 


Drag Hems to specify the order m which they open. 

To hide Ail application When ynu log in, dUrk its HWe checkbps 


Login control panel showing Login Items 
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The next panel of interest is the Login preferences 
panel. This controls Login functionality, such as automatic 
log in in the Login Window tab. Plus you can choose your 
enabled startup items in the Login Items tab. 

The reason for moving the startup items is based 
on the multi-user capability of Mac OS X. If you have 
twenty people sharing the computer, anti they all have 
3 different startup items, you wouldn’t all the 
applications to start for everyone. tThe applications 
only start up when you log in, and that way only your 
choices start up. This is also the location of another 
beta bug. Once you set up the link to an application, 
if you move the application, the link is broken, 
indicating that UnLx-style hard links are being used, 
instead of proper aliases. This can be quite annoying, 
but l doubt that Apple would leave such an interface 
bug like that in the final version. Also worth noting is 
that if you are the only user for a given machine, you 
can set it to automatically log in for you, so that you 
do not have to go through the log in process. Another 
option in the Login Window tab disables the Restart 
and Shut Down buttons. This is useful if aMacintosh 
computer is being used as a server, the only way to 
restart it would be through the hard switches on the 
computer, or by logging in as root. One note here, if 
you do have the automatic log in enabled, you should 
never set it to root. As the super user for a given 
system or network, there is nothing that root cannot 
do, and therefore that user should never be the 
default user for any machine. 


TCP/IP tab of the Network control panel 

The third panel we will look at is the Network 
preferences panel TCPAP is the first tab, and looks familiar 
with the exception of the Host Name, The host name is used 
to identify the machine, not only via DNS, (in my case, 
valkyrie.aer.com), but for AppleTalk and Netlnfo as well. 
What isn’t shown, and unfortunately 1 couldn’t get a good 
screen shot Ls the fact that the TCP/iP panel has 
configuration settings. 1 have had two separate static IP 
addresses on this PowerBook, and if you could see the 
Configure: pop-up menu, you would see: Manually 10.2.4.4, 
Manually 10.2.4.1, along with DHCP and Booth. This 
configuration support is a good sign that Location Manager 
is not gone, as many fear, just not completed yet. 

The next tab is AppleTalk, and is fairly simple. 
AppleTalk is toggled on and off with a checkbox and 
you type in the AppleTalk Computer Name, The 
Netlnfo tab simply asks if you want to connect to an 
existing Netlnfo domain or not. The fourth tab is the 
Services tab, and that bears a little more investigation. 
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Click tlw leek 1& prevent hirtfier changes 


f fttvart ^ f Apply 


Services tab of lb e Network control panel 


The Services tab handles the Web Server that is 
included with Mac OS X, namely Apache. Well over 
60% of the Internet is run off of Apache, and with the 
full version of that web server, Apple is giving Public 
Beta users a very powerful way to publish documents 
and files. This also makes the initial decision as to 
which web server to use with Mac OS X very easy, but 
it creates an interesting business proposition for the 
Web STAR folks. 4 D, Inc. now needs to give their 
existing users a compelling reason to stay with 
WebSTAR, and create a more compelling reason for 
people to buy WebSTAR instead of staying with a free 
product that is every bit as powerful. However, the 
Services tab only turns Apache on, and lets you decide 
where you want the documents to reside. It doesn’t 
configure Apache, or make it secure, so there is still a 
lot of work left for the user to do. This also is where 
Apple, or third party developers can come in, and 
create products that help you configure Apache in a 
way that makes the Mac community comfortable with 
such a powerful tool. Another advantage to including 
Apache is that it finally gives the Macintosh Web 
community access to all the powerful Apache tools , 
including, potentially the Apache add- ons that allow 
you to use Apache as a server for Active Server Pages, 
instead of Microsoft's Internet Information Server. IIS. 
Opinions of Microsoft aside, ITS is a major player in 
business intranets, and Apple has always been forced 
out of this large, lucrative arena, Apache gives them a 
toehold here, and a fairly respectable toehold at that. 
Considering the amount of Web content created on 
Macs for other server platforms, it’s about time that Lhat 
content can be served on a Mac without die potshots 
directed at the Mac OS. 

The next stop in System Preferences is the Screen 


Saver panel. Although not thought of as an 
administrator kind of application, the fact is, most 
servers have a timed screen lockout system. The 
settings for the screen saver do not currently allow for 
forcing a password to get past the screen saver, which 
makes it less useful to administrators. Apple, or a third 
party developer should be able to provide a solution. 
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Screen Saver control panel Activation tab 


The Sharing preferences panel is next on our tour. 
This controls a number of items of interest to users and 
administrators. 
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The File Sharing button controls Mac OS X’s Apple 
File Protocol (AFP) over TCP/IP sharing capability. The 
Public Beta only allows you to share your Public 
folder, but like a lot of this version, this looks like a 
beta bug, and should be fixed quickly enough. The 
other two checkboxes are new to Mac users, The first, 
Turn on remote Telnet access, enables the Telnet 
server that ships with Mac OS X. This is a very handy 
feature for administrators, as it gives them the ability to 
log into a Mac OS X machine, and perform any of the 
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standard Unix remote administration tasks that can be 
run from a command line. This is also a dangerous 
feature for the very same reason. Tf a computer cracker 
were to Telnet to an OS X box running Telnet services, 
and be able to log in as root, again, this person would 
have complete control of the Mac OS X box from a 
command line, and then do essentially, anything that is 
possible from a command line, which in Unix is quite 
a lot. (I don’t want to sound too alarmist here, as 
having Telnet access to OS X is an incredibly useful 
feature, especially to those of us who are network 
administrators. As with any feature, it has its downside 
as well. The command line, and command line access 
are not inherently bad or good, but like any tool, can 
be used both ways. Mac OS X ships with Telnet turned 
off, and unless you have an explicit need for this 
feature, I would recommend keeping it off. A lot of the 
security of the Mac OS has been due to the lack of 
remote access features in the OS. While this has saved 
a lot of Mac administrators from having to deal with 
crackers, it has also restricted administrators from the 
kind of capabilities that our Unix and Windows 
compatriots have. Services, daemons, and applications 
like Telnet, and other Unix capabilities are going to 
give us a lot more power, and a lot more things to 
worry about. It's better to start now, and he ready, than 
to find out the hard way when some script kiddie turns 
your machine into a DOS attack zombie. 

The other setting in the Sharing settings panel 
enables the FTP service. So your Mac can be a FTP 
server out of the box, no extra software required. 
Again, my warning about security applies here as well, 
if you have either of these services turned on, be sure 
to pick a good password for root, and change it often. 
Even with Telnet turned off, a cracker with root access 
could FTP to your machine, and replace die 
configuration file that turns off Telnet with one that 
turned it on, and a script that would notify him or her 
that access was now on. The next time that machine 
rebooted, that cracker would have full access to your 
Macintosh. Ssome common sense keeps you safe, if 
you don’t need to be an FTP server, leave that service 
turned off. If crackers can't get in to your machine, 
they can’t make use of it. [f you need this service 
turned on, Lhen change your root password regularly, 
and make it incredibly cryptic. This is one area where 
an ounce of prevention is worth a ton of cure. The 
final section of the System Preferences we will look at 
is the Startup Disk preferences panel. 
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Startup Disk control panel 

The Startup Disk preferences panel is where you 
choose the operating system you wish to boot from, 
whether that be on a separate disk, as shown above, or 
on the same disk. Like other settings in the System 
Preferences, you have to be an administrator on the 
machine to change any setting in this preferences panel. 

Other Settings 

There Is one other place that is normally used to set 
up Mac OS X, and that is Multiple Users, (I am leaving 
out the Keychain setup, as it seems to be unchanged 
from Mac OS 9.) This is where you would normally 
create, edit, and delete user accounts on your Mac OS 
X machine. Multiple Users is a much simpler beast than 
its OS 9 counterpart, and is more intuitive to use. 

42 Q^Q- - _ Multiple Users _ 

Name_Kind_ 

Joh n C Welch Admin New User 

Alex Welch 

Open Uy»r \ 


£ Click the lock to make changes. 

A 

Multiple Users main screen 

One of the first things that you notice is that one 
account is missing, namely root. This is a good thing, 
because it means, that even if 1 unlock Multiple Users 
to make changes, I cannot touch root, either to delete 
it, or change its password. There is an interface for 
altering root, which we will look at in a bit. Multi pie 
Users allows you to add, edit, or delete users. You 
musL be an administrator to gain access to its features. 
Once inside the application, editing a user is fairly 
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simple. As shown below, you can change the Name, 
Short Name, (the userid), the Password for the user, 
and decide if that user can be an administrator . If the 
user is an administrator, then their userid and 
password will unlock those settings panels and 
applications that can only be used by an administrator. 
Granting this privilege should not be done unless that 
person needs Lhat kind of complete access. 




Name: John C Welch 

Example Mary JDues 

Short Name jcwelch 

Example mjones {8 characters or fewer, no spaces) 
Used for FTP, Telnet, ere. 

Password: .. 

Verify: ■*•»**■•<*••* 

Retype password 

2f Allow user to administer this machine 


Cancel ^ 


Multiple Users showing the options 
for editing an existing user 


Manager. When you first open it, you are presented with 
the root, or / view of localhost, which is Unix for Lhe 
machine you are sitting at. If you have the proper 
privileges, you can also use Netlnfo Manager to manage 
entire Netlnfo network domains, but for this article, we’ll 
stay on the local machine level. 



Directory / 



: 

S Ctafe s he talk 1<* Irtatc Chjrltjti. 


The screen for creating a new user is identical to 
the edit user screen, except that when you open it, 
none of the fields are filled in. This discussion takes 
care of the common settings interfaces that you will 
use for Mac OS X. Our next step is to take a look at 
the less common interfaces for setting up Mac OS X, 
namely Netlnfo and the Unix settings files. 

Netlnfo 

Netlnfo is the administrators tool for setLing up not 
only individual OS X, OS X Server, and NeXT 
machines, but for configuring networks as well, it is an 
amazingly powerful tool, and used correctly, can make 
much of an administrator's job easier. Unfortunately, 
outside of the NeXT and Mac OS X (Server) 
community, Netlnfo is hardly used at all, being 
superceded by products like Novell Directory Services, 
NIS+ from Sun, Active Directory from Microsoft, and 
LDAP. This is not to say that Netlnfo isn't a capable 
tool, quite the contrary-it can easily match and in 
many cases beat the capabilities of these other systems. 
Since Netlnfo is a minority player* Apple needs to do 
much more work on integrating Netlnfo with these 
other systems, particularly NIS+ and LDAP* as these are 
the major players in the Unix world. 

The application that administers Netlnfo is the Netlnfo 


Initial Netlnfo Manager Screen 

As you can see above, the Netlnfo Manager uses 
the same type of browser interface as the Finder. The 
/ indicates the root level of the computer, analogous to 
the Computer level of the Finder. The middle pane 
shows the items that are controlled by the Netlnfo 
manager, and although we won’t cover all of them, 
some of them are worth discussing. First we should 
look at some of the items in Config, such as 
AppleFileServer and nip. If we look at the 
AppleFileServer screen below, we can see that Netlnfo 
does give us access to the settings we need* even if the 
interface leaves something to be desired* 
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so much for every Mac user! 

Check out the Special Interest 
Boulevards while you are exploring the 
exhibit floor to find and compare hot 
new products for your particular needs. 
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• Digital Multimedia 

• Music and Audio 

• Developer Central 

• Net Innovators 

Be sure to visit www.macworldexpo.com 
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Macintosh technology. The Pro conference 
offers the most sophisticated training 
available on Mac networking, digital video, 
art director/creative management practices, 
and Mac systems administrations for 
large organizations. 

Macworld/Users continues to be one of 
the best educational values anywhere. 

The Users conference features industry 
experts offering skill development on 
the most popular Mac-related tools and 
professional development courses 
for users who rely on Apple technology 
to gain a competitive advantage. 

MacBeginnings- San Francisco debut! 

After great success this July in New York, 
MacBeginnings will make it's debut 
in San Francisco! These high-energy, 
informative sessions will provide 
first-time attendees, new and beginning 
Mac users a starting point to enter 
the Mac community. MacBeginnings are 
free and open to Ml registered Macworld 
Conference & Expo attendees! 
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Net Info Apple Fi leSe rve r Set i i \ tgs 


To me, and admittedly I am not a NetJnfo expert, nr 
even a Net Info power user, this is a mix of good and bad 
interface components, Good, because l have quick access to 
any setting that an AppleSharelP Server needs to have, and 
it’s in a consistent GUI. Bad, because since there is no 
Netlnfo Manager help in the Public Beta, i am forced to 
guess, at what are some of the settings. Ii may be obvious 
dial the idle_disconnect_iime should be talking about 
minutes, but it would lie handy to have that made more 
obvious. Nonetheless, the Netlnfo Manager does give me 
the features l need to set up this sendee on my Mac OS X 
machine, The guest_access setting is less obvious, but one 
would suppose that this setting uses a binary setting, since 
other settings in this pane dol, so for now, guest_access is 
turned off* Moving down, we can see that the idle 
disconnect settings for all users, regardless of level, is turned 
on as well* The activityJogjsize is set to what I would guess 
to be around a megabyte in size, as if it were a kilobyte, 
then it would not be able to hold many entries. We can also 
see the login greeting for this machine, and what activities 
are logged. It Ls good to note that almost all activities are 
logged If you did suspect someone has cracked your 
machine, good usage logs are some of the Ixast ways to find 
out what is going on, and who is doing it. 

The path where the activity log is kept is the next 
setting, and although mine Is left at the default 
location, the wise administrator will change the default 
so that a cracker cannot alter the log to hide their 
tracks. The port used for AFP over TCP/IP is the next 
setting, which is needed if you want to set up a 
firewall to allow this protocol through the firewall. 
Moving down the list, the idie_disconnect appears to 
be turned off, a security weakness, were this an actual 
server. The reg__AppleTalk setting would appear to be 


the one to allow for straight AppleTalk to be used. As 
I have not yet confirmed this, I am leaving it alone. 
(This brings me to my next warning. If you don't know 
what a setting does In Netlnfo, leave it alone. The 
Netlnfo Manager is how you, as an administrator, can 
set up features on an Mac OS X machine that are not 
available in the conventional settings panels. It is also 
an easy way to send your Mac OS X machine into 
limbo at light speed. Any changes I have made in 
Netlnfo Manager have only been made after I was sure 
that 1 knew what 1 was doing. ) The final setting on this 
page that we look at is the register_NSL setting, which 
when turned on, as it is here, allows this machine to 
show up as an AppleSharelP server in the Network 
Browser application. 

The other setting in con fig that we want to look at is 
the ntp setting* There isn't much here, but it does show 
you the relationship between the System Preferences and 
Netlnfo. If you look back at the screenshot of the network 
time tab in the Date ik Time control panel, you can see 
where I had manually entered a timeserver name. Looking 
at /Config/ntp setting below* we can see that the Date & 
Time control panel setting was automatically entered into 
Netlnfo for us. Hopefully* Apple will continue to provide 
more intuitive interfaces for other Netlnfo settings, 
limiting the amount of time non-administrators would 
need to spend here. 



Net / 11fo se tt i iigs _ fh r /config/nip 


Another example of how the System Preferences 
set Netlnfo parameters is the /loea Icon fig/a ppl eta lk 
setLing. This Ls what is set when you enter a machine 
name in the AppleTalk tab in the Network settings 
panel, as you can see next. 
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Searchable Databases 
Online Stores 
Info Baskets 
Guestbooks 
Banner Ads 
Credit Card Transactions 

Counters 
Password Protection 
Surveys 
Quizzes 
Form Processing 
Conditionals 
Math 
Cookies 


It's time for you to take a look at MGI 

MGI, a plug-in to 4D‘s award-winning server, WebSTAR, is 
designed to provide functionality to otherwise static web sites, 
whether for a private intranet or enterprise - class ISP/ASP. 
MGI was specifically developed to be used by web graphic 
designers with no scripting or programming experience. If 
you know HTML, you know MGI. And if you are a 
programmer, you can learn MGI by the time your pizza is 
delivered. You can try out MGI for free - right now - without 
obligation by downloading a fully - functioning demo at: 


j\ 


http://www.pageplanetsoftware.com 


•mm 


SOFTWARE BUILT WITH YOU IN MIND 


3 agePlane1 SoIlwar© lnc. t 3252 Oclavia Sirooi. Raleigh, MO P7GOG 919,233. 1770 













/lac a Ico nfig/appletalk setti ngs 


It’s neat to see how Apple can make dealing with 
Netlnfo more simple. What about things that aren’t in the 
System Preferences, such as Network File System, NFS 
access? Since Mac OS X is based on Unix, and NFS is the 
standard way for Unix systems to share drives and directories 
across a network, how do you do that? Well. this is one place 
where Netlnfo saves you from setting up NFS automoLints by 
directly editing con fig files. As we can see in the example 
below, 1 have two NFS shares set to automatjeally mount 
when I log in to Mac OS X on my PowerHook. 



IA] 


/m o u n ts/eig h t y-eigh t:/p u hi ic 

The first parameter of each entry is the vstype, in this 
case NFS. This tells Netlnfo what type of drive it's going to 
be mounting, as there are different ways of handling 
different types of mounts. The next parameter is dir, which is 


the local directory where the mounted drive should appear. 
This is where Mac OS X’s Unix base shows up. In Unix, w hen 
you are going to mount a remote drive via NFS, you not only 
need to know the computer, and the partition you wish to 
mount, but you need to tell your computer where this remote 
mount should be attached to locally. In most cased, with OS 
X, you want this to be in a subdirectory of Network, which 
we saw in the earlier Finder screen shot. Now within 
Network, there is a folder called Servers, but only the system 
can alter that directory, so 1 have set all my mounts to be 
subdirectories of Network, In the example shown, 1 call it 
public, so the value for dir in this case is /Network/public. 
Note that creating it here does not create the actual directory. 
You still have to do that either via the Finder, or the 
command line. Although experienced Unix administrators 
will have no trouble with this, Mac administrators* may find 
this inconsistency will trip them up. Hopefully, a more 
coherent interface for managing NFS mounts in Mac OS X 
will show up as the final release date nears. The next 
parameter is the name of the remote computer and the path 
to the directory that I wish to mount. This follows the Unix 
convention of <machinename:/path>. In this example, the 
machine name is eighty-eight, and the directory 1 wish to 
mount is at the root of the system* and is named public, so 
the value for name is ‘eighty-eigho/public’. The final value is 
opts, for options, and the only thing entered here is bg 1 , 
which tells the system to mount [his share in the background. 
Any other mounts are set up the same way, and so far, every 
lime I log in, the mounts have been there. 

This brings me to another inconsistency in Mac OS X, the 
way it handles different types of mounted drives. If 1 connect id 
an AppleShard? server, the share shows up on the desktop, 
and goes away when I disconnect. Any NFS shares created in 
Net info Manager seem to be always mounted, even if the 
computer is not on the network, because a permanent directory 
is created so that the NFS share has something to attach to, If 
you are used to Unix, this is nothing unusual. However, in the 
Mac world, if you aren't attached to that share, it has no 
business existing at all on your machine, 1 actually like this 
better, as li is a dear way of notifying the user that this or that 
sf mre is a vaila I>le for use. HofDefy 11 y, this will I >e fixed, either by 
Apple, or an enterprising third-party developer. 

The next part of Netlnfo that bears looking at is the 
/groups section. These are Unix user groups, similar to the 
groups you would set up in any network. The ones shown 
below are the standard groups that ship with Mac OS X. Of 
particular interest to the network administrator is the wheel 
group This is the group you are assigned if you are created 
as a user that can administer this machine, sys, which on a 
stock install has root as its only member, and admin, which 
also shows root as its only member. Groups are an important 
tool in Unix security, and can be a great help to an 
administrator if set up correctly. Conversely, they can also be 
a nightmare to an administrator if used incorrectly. As you can 
see, there are groups that are application/purpose-specific. 


52 


Mac OS X Public Beta 


MacTech * November 2000 































“Never forget that the most powerful 
force on earth is love.” 

-Nelson A. Rockefeller 


t$J 

Move over love. 


Get a new Apple PowerMac™ G4 all ||A|i 

or one of our refurbished models if *'£> V;, . S 

at price you will L-O-V-E. I|. T * ElCCt TOIliCS 


1673 Main Street 
Waitsfield,VT 05673 USA 
Phone: 802-496-7171 
Online: small<Jog.<om 



Apple Specials 


©2000 Apple Computer. Inc. Alt rights reserved. The Apple logo is a registered trademark and PowerMac is a trademark of Apple Computer, Inc 




such as www, mail, news, etc. This is so certain types of 
applications, (and with Unix, the word 'application’ is used 
very Loosely), can have the low-level access they need to 
function, without needing to operate as root. Remember, root 
should not be used lightly or often, (If it seems that I am 
really beating this with a stick, I am, I have seen too many 
networks standing on their heads with all kinds of arcane 
passwords for users, limiting login times, disk quotas, etc, 
only to be easily hacked because the administrators were 
constantly logging into the system as root, remote logins as 
mol were allowed, and too many applications were running 
as root. The fact that Apple disables remote root login by 
default in Mac OS X is a good sign that they want it to have 
the same level of out of the box security as OS 9 does.) 
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Netlnfo /users/alex pane 


The sharedDirAlias is interesting, as it highlights the 
heavy use of XML in Mac OS X, along with how powerful 
XML can be. Some of the hacks starting to circulate that allow 
AirPort cards to function, for example, are nothing more than 
XML entries. Although it's hard to tell at this stage how much 
use of XML Apple is going to have in the final release, it’s 
fairly extensive in the Public Beta, As an example, almost all 
your preference settings for Mac OS X are kept as .plist files, 
which are nothing more than XML files. 

An example is the ApplePowerManagement.plist file, 
which is the where the Energy Saver control panel settings 
are stored: 


Net Info /groups pane 

The next part of Netlnfo we look at is the /users section, 
This is where every user that is entered into multiple users 
shows up. The entry we are looking at is one I created for 
my son, Alex. It shows the information tor his full name, and 
his login name. The home entry shows his home directory, 
/home/alex. The entry for _shado wpass wd is blank. From 
the information 1 could get on Netlnfo off of the Internet, this 
is because Netlnfo doesn't use shadow passwords, as they 
are less secure than Netlnfo's method of storing passwords. 
The shell entry 7 shows his default command line shell, should 
he choose to use it. It also shows his userid, 103, and his gid, 
or group ID, 20, Just like any other Unix, you can belong to 
more than one group, and the first number shown in the gid 
entry is the user’s main group. 


<?xml version="l, (T enc odin g=" UTF- 8 " ? > 

< ! DOCTYPE plist SYSTEM 

file: //loealhost/System/Library/DTDs/PropertyList.dtd w > 
<plist version =,i 0.9 f% > 

<dict> 

Ckey^DisplaySleepTimelfilndependent^/key^ 

<true/> 

(key^HardDiskSieepTimeIs Independent</key^ 

<true/> 

<key>MimitesUntilDisplaySleeps</key> 

<integer>0</integer> 

Ckey>MinntesUntilHardDlskSleeps</key> 

<integer>3 0 </intege t> 

<key>MinutesUntilSystemsIeeps</key> 

K intege rO £}C/integerk 
</dict> 

</pii£t> 

This is a standard XML 1.0 file, with a custom DOCTYPE, 
referencing a DTD that sets up the parameters for a property 
list. The entries that follow are fairly easy to read as well. It 
shows that display and hard drive sleep times are 
independently set. The Display sleep is set to zero minutes, 
along with the system sleep time, and the hard drive time is 
set Lo 30 minutes. This is a case of a beta bug as well, since 
the entries for the hard drive and system sleep times are 
nicely reversed. I’m not too upset, because the power 
management issues are pointed out in the Read Me. 
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Hie final part of Netlnfo Manager we should look at is the 
services. We will not alter anything here, but it is gtxxJ for showing 
that Mac OS X does ship with die standard Unix services, or ability 
to run diem, even if all tire not enabled in the Public beta. Available 
services like pop3, rje t simp, syslog, talk, telnet, timed, uucp, sump, 
and whois, point to Mac OS X being able to be a full-featured player 
in die Unix and networking worlds. 



Netlnfo fsewices/snmp-Lntp 


So How Does It Work? 

Well, so far, quite well. The network speed is very fast, 
and a nice improvement over 05 9. As a test, t was able to 
achieve saturation speeds on a 100Mb Ethernet network for 
a 250MB file copy, and while that was going on, 1 was doing 
other transfers as well. The only slowdowns were due to 
network bandwidth limitations, not OS limitations. Web 
browsing, and FTP fed snappier than in OS 9. The ability to 
telnet into my Mac, and kill a process that was eating CPU 
was something to warm my administrator's heart. Even nicer 
was the OS telling me a process had been killed, but that 
everything was still okay. 

From the Unix side of things, all the command line 
capabilities are there, and with the beta of XTools from 
Tenon sitting on my OS X box, and running Netscape on a 
Solaris box, and IDL on an SGI was just too sweet. It’s a full 
Unix environment, and it works like one, and acts like one, 
both good and bad. Apple has just managed to make it 
better. All the low level Unix bits are there, including, /etc, 
/var, sendmail, and hostconfig, but you never have to see 
them if you don’t want. In the two weeks of constant use, 
I’ve only been in the config files by choice, not by necessity. 
The System Preferences and Netlnfo take care of that for you. 
In fact, thanks to Netlnfo, many of the Unix config files aren't 
even used, but are there as a backup system. AppleScript is 
even there, although it is very rough as of yet. I plan to look 
heavily at that very soon. 


The fact that Mac OS X gives you all of its power and features 
in a uniform, coherent interface is the most important part of the 
operating system. Hie Unix underpinnings, which are powerful 
and complete, are worth a look at in a second article. Aqua is more 
than more than pretty buttons and colors, it’s a way of taking a 
powerful, yet obtuse OS, (Yes, Unix may be user friendly, but it's 
picky about who its friends are), and giving that power to 
everyone, not just the experts. There are tilings in Mac OS X that 
are no different than in X-Windows, Gnome, etc. Hie difference is, 
it’s friendlier, and the OS tells you what is going on. Hie error 
messages are friendlier than OS 9’s and tar more friendlier than 
standard Unix. It does what it is supposed to do, and for the most 
part gets out of your, (well at least my), way while doing it. Yes it 
looks and acts different, but at heart, it’s still the Mac OS, just in 
better shape, and with a new suit. Its kind of like Steve Austin after 
die bionics, faster, stronger, better. 

Well, we covered a lot, and there’s a lot to go. I didn’t get to 
Classic, as that isn't something that is workable for me right now, 
and it's also been covered in depth, I only touched lightly on the 
Unix underpinnings, a.s I just haven’t had a lot of time to really play 
with them. Hopefully, you have a I letter idea of how and maybe 
even why some of Mae OS X works the way it does. Remember, a 
lot of this can, and possibly will change, so if I seem to have 
avoided certain areas, that’s why. Also, there is not a lot of 
administration-type documentation, which Is a weakness with a lot 
of Apple products. OS X Server is a prime example. The Mac OS X 
Admin list from Omni Group is a tetter source of information than 
Apple for that product, and that’s not right, Mac OS X is a product 
that is going to open up too many doors for Apple to be 
lackadaisical with Administration documentation. Whatever 
mistakes Microsoft and IBM make, they have always made sure the 
people running their products have really excellent support, as well 
as the people creating product for them. In Apple's defense, they 
do have the correct attitude, and with a little more documentation, 
they can make sure that the admins of the world are as well 
prepared for tills OS as the developers. 

In any event, Mac OS X is sure to be a w r ild ride between 
now and the full release, and this is only the first of many 
articles that you'll see in MacTech to help you make the ride 
as smooth as possible. 
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MAC OS X 


By Andrew C. Stone 


Recursion:The Programmer’s Friend 


A programmer's bag of tricks is 
loaded with heuristics, algorithms and 
techniques, but of these, few are as 
powerful as recursion. The Oxford 
English Dictionary recursively defines 
recursion as "The application or use of a 
recursive procedure or definition"! 
Recursive has the definition u Involving or 
being a repeated procedure such that the 
required result at each step except the last 
is given in terms of the results) of the next 
step, until after a finite number of steps a 
terminus is reached with an outright 
evaluation of a result." 

In software, recursion is when a 
function or method calls itself, over and 
over, with slightly differing arguments. Of 
course this sounds like the perfect recipe 
for an infinite loop, but we will design in 
an exit condition so you don't end up in 
Cupertino! Recursion allows the writing of 
elegant and terse code once you 
understand how it works, 

Recursion abounds in nature, and 
can be visualized by thinking of the 
fractal Mandelbrot set — no matter how 
deep into the set you continue to go T the 
same forms appear over and over, in an 
increasingly minute, yet perfectly 
replicated form. 

Programmers often use a recursive 
data structure called a tree to represent 
hierarchical data. A tree is a root (Now 
that’s an oxyomoron!) with zero or more 
subtrees. Each subtree consists of a root 
node with zero or more subtrees* A 
subtree node with no branches or children 


is a leaf node. (Tree terminology uses both botanical 
(root/branch) and geneological (parent/child) terms.) A classic 
use of recursion is for tree traversal, where you want to perform 
some action on each node in the tree. 



A tree can be implemented in various ways, depending on 
the structure and use of the tree. It’s beyond the scope of this 
article to cover the implementation of "scales well to large N f> 
trees such as the btree; however for a reasonably small number 
(e.g, under 1000) of nodes, arrays of arrays will work fine* Let’s 
define a simplistic Node as: 

^interface Node f 

id data: //an opaque pointer to some kind of data 
NSArray ‘.children: 

// if an internal node, this contains children nodes 
// if this is a leaf node, it contains 0 dements. 

// query the Node: 

(NSArtay *)children: 

- (NSData *}data; 


Andrew Stone <andrew@stone,com> is founder of Stone Design Carp <http://www.storte.com/> and has spent 12 years 
writing Cocoa software in its various incarnations. 
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// establish the Node: 

- (void)setChildren:(NSArray *)newKids; 

- {void)setData:(id)data; 

@end 

And our tree controller object would look like: 

^interface TreeController f 

Node * _rootOfTreeNode 3 // the mot is all you need to get at any Node 

(void)visitNode:(Node *)node; 

- {voidJprintData;(Node *)node; 

@end 


Walking a Tree: Kinds of Traversals 

There are three types of tree traversals: preorder, 
inorder. and postorder - each defines the particulars of 
whether you work on a node before or after working on its 
children. In preorder, you work on the parent and then do 
an inorder traversal of each of the children . In inorder, you 
do a preorder traversal on the leftmost child, work on the 
parent, and then do an inorder traversal of each of the 
remaining children. In postorder, you do a postorder 
traversal of each of the children and then work on the parent. 

Here’s the code for a recursive preorder traversal: 

- [void)visitNode:(Node *)nade [ 

NSArray 'childrenTcjVisit = [node children] ; 
unsigned I, count = [ehildrenToVisit Count]: 

// visit the current node: 

[self print Data-:- Inode data! ] , 

// if there are no children, then recursion ends: 

for {i = 0; i < count; i++) // make recursive call: 

[self visitHode:[childrenteVisit objectAtlndex:!]]; 


■ (void)printData;(Node *)node j 

// this is just an example in reality you might dt> something useful! 

NSLog([node description}); 

1 

To traverse an entire tree, you would simply start the 
recursive process at the top of the tree by calling our method 
with the root node as the argument: 

[self visItNode:_rootOfTreeNode]: 

Note that to perform a postorder traversal, you just move 
the “printData” (our placeholder for the action we wish to 
perform on any node) to the bottom of the method: 

- visitNodePostorder: [Node Hnode I 

NSArray *childrenToVisit = [node children]: 
unsigned 1, count = [ehf IdMriToVisit Count]: 
for Ci — Or i < count; ±++) 

[self visitNodePostorder: [childrenToViait objectAtTndex;ij]: 

// now visit the current node; 

[self prlntOatEi: [node data]]. 


Stacks and Stacks of Stacks 

So how does tills all work? Every programming language 
that supports recursion (including Objective-C) maintains a 
stack of information about parameters and local variables for 


each time a procedure, function, or method is called. When 
a procedure is called, the information is pushed onto the 
stack; when the procedure exits, the information is popped 
front rite stack. 

Given the tree pictured in Figure 1, let's mentally walk 
through what’s happening. First we call visitNodePostorder: 
on the root node (node A), placing this method call on the 
stack. Node A has 3 children so we call visitNodePostorder 
on the first child (node B), pushing that call on the stack. 
Node B has 2 children, so we call visitNodePostorder on the 
first child (node C), placing that call on the stack. We then 
call the method on node Cs first child, node D. Now the 
stack is 4 deep, but this final node is a leaf, so we call 
print Data on node D. We’re back in visitNodePostorder:C and 
the second child (node E) is called, increasing the stack to 4 
again. Since it is also a leaf, we print it, pop the method call, 
and weTe back down to 3, Now node C will print itself, and 
we're down to 2 deep in the stack, The second child of node 
B is a leaf, so we go 3 deep, and after printing, we’re at 2 
deep. Node B is then printed, and then we’re back to the first 
frame in the stack (node A), on the second iteration of its for 
loop. Since the second child (node G) of the root node is a 
leaf, it gens printed, and we’re on the third child And so on 
for the rest of the tree. 

print :tl print: £ 

visit;!} vintt:D vlattiD viflitjfi viH±trE vJjitiE 

vissciC viflitiC visit:C visit:C viait:C vL«it:C visit;C Visit ;C 
uiaitsB vieil. t visit;?, vl-nitiB visit iB yiBitiB visits visit3H 

visit :A visit:A vlaitiA visttiA Visit:* visit:* visit:* visit:A visit 1A 


print tC print 1F 

vtsitfC vieitiC visit : F VisitVIBit rF prints 

visit:B viaitrB visit:? visit:? violtiB visittfl visit:B visit lH u tc 

visit :k visit 2 A WI-: ■ ■ ; ■ . " A vi^Urft visittA 

Figure 2 , Snapshots of the stack during the tree traversal. 

So, you can see that the stack wall grow to the depth of 
the tree. If you are working with very deep trees and you’re 
concerned with implementation efficiency and want to avoid 
the overhead inherent in making method calls, you can 
remove the recursion by managing your own stack of 
variables. However, this results in much more complex, less 
elegant, less maintainable code. I'd avoid it in all but the 
most extreme situations. 

Conclusion 

As programming challenges arise, remember this 
recursive jewel I learned many years ago in Computer 
Science school: if you cannot tackle a problem, divide iL into 
smaller problems which you can tackle. Eventually you’ll 
have wittled the problem down to something manageable, 
and applying this recursive problem solving tool will usually 
result in a readable and maintainable software solution. 
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I QUICKTIME 
TOOLKIT 


by Tim Monroe 


Word Is Out 


Using Text in QuickTime Movies 


Introduction 

When QuickTime was first introduced, it w r as able 
to handle tw^o types of media data: video and sound. 
Curiously, the very next media type added to 
QuickTime (in version 1.5) was text , or the written 
word. Part of the motivation for adding text media was 
to provide the sort of “text below' the picture" that you 
see in movie subtitles or television closed-captioning, 
as illustrated in Figure 1. Here, the text provides the 
words of a song, which can be useful to hearing- 
impaired or non-English speaking users. Similarly, the 
text might provide the dialogue of a play or a readable 
version of the narration. Of course, the text doesn't 
have to just mirror the voice part of an audio track; it 
can be any annotation that the movie creator deems 
useful for the viewer. 



Figure 1: A movie containing a text track. 


The text you see in Figure 1 is not pan of the 
video track; rather, it is stored in a text track (whose 
associated media is of type TextMediaType). Typically 
the text track is situated below the video track (as in 
Figure 1), but in fact it can overlay part or al! of the 
video track. In order for both the text and the overlain 
video Lo be visible, the background of the text track 
should be transparent or "keyed out”; the text is then 
called keyed text Figure 2 shows some keyed text 
overlaying a video track. Keying can be 
computationally expensive, however, so keyed text is 
seen less often than be to w-t he-video text. 



Figure 2; A movie containing a keyed text track, 


'rim Monroe works in the QuickTime Engineering group at Apple. You can contact him at monroe@apple.com. 
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Quicklime provides the capability to search for a 
specific string of characters in a text track and to move 
the current movie time forward (or backward) to the 
next (or previous) occurrence of that string. In addition, 
the standard movie controller provides support for a 
special kind of text track called a chapter track. A 
chapter track is a text track that has been associated 
with some other track (often a video or sound track); 
when a movie contains a chapter track, the movie 
controller will build, display, and handle a pop-up 
menu that contains the text in the various samples in 
that track. The pop-up menu appears (space 
permitting) in the controller bar. The various parts of 
the associated track are called the track's chapters. 
When tire user selects an item in the pop-up menu, the 
movie controller jumps to the start time of the selected 
chapter. Figure 3 shows our standard appearing- 
penguin movie with a chapter track that indicates the 
percentage of completion (both before and after the 
user clicks on the pop-up menu). Notice that we've had 
to hide the step buttons in the controller bar to make 
room for the chapter pop-up menu. Notice also that the 
text track itself is not visible. 



Making the Move 


With jjjrjr: [jfj ,'(just over the 
Mac icydofCCB everywhere have a 
major need for C AR B ON and 



Figure J; A movie with a chapter track , 


application porting, user interface 

implementation, and Hls ll development 
services. Toward that end, several 
high-quality engineering 

firms, in association with the RPPLf 
tifUELOPER CONNECTION, are offering these 
services at very aJJrCicJjue discounts 
to all rjj C Select and Premier members. 


The QuickTime Player application, introduced with 
QuickTime 3,0, employs a slightly different user interface 
for accessing a movie’s chapters. As you can see in 
Figure 4, a QuickTime Player movie window replaces 
the pop-up menu with a set of up- and down-arrow 
controls, which select the previous and next chapter. 
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Since 1991, high tech companies like Apple Computer, 
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Art & Logic for assistance in implementing cutting 
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untitled, mov 



Figure 4: The chapter controls in a QuickTime 
Player movie wintltntK 


QuickTime 3-0 also included a web browser plug¬ 
in that supports linked text. Linked text is contained in 
a hypertext reference track (usually shortened to HREF 
track), which is simply a text track that has a special 
name (to wit, “HREFTrack”) and contains some media 
samples that pick out URL links. If a text sample 
contains text of the form the QuickTime Plug- 

In will load the specified URL in the frame containing 
the movie when the user clicks in the movie box while 
that text sample is active. (Let’s call this a clickable 
link) If the text is if the form A<fM>, then the plug¬ 
in w r ill load the specified URL automatically when that 
text sample becomes active, (Let’s call this an 
automatic link) 

QuickTime 4 added one more text-handling tool, 
the ability to attach wired actions to data in a text 
track, A wired action is some action (such as setting a 
movie's volume or its current time) that is initiated by 
some particular event. The events that can trigger 
wired actions include both user events like moving or 
clicking the mouse and movie controller events like 
loading movies or processing idle events from the 
operating system. We ll investigate wired actions at 
length in a future article; for the moment, consider the 
movie shown in Figure 5, This movie contains only 
one track, a text track. The text track is configured so 
that clicking on the word “Apple” launches the user's 


default web browser and loads the URL 
http://www.apple.com; in addition, rolling the cursor over 
the word “CNN” loads the URL http://www.cnn,com/. 
{Let’s call this wired text.) 



Figure 5 A text track with wired actions. 

in this article, we're going to take a look aL the 
most basic ways of handling text in QuickTime movies. 
After we take a brief detour to upgrade the code that 
adjusts our Edit menu, we’ll uncover some w r ays in 
which our existing sample applications can already 
interact with text. It turns out that these applications 
can do a surprising amount of work with text tracks; 
indeed, they can even create text tracks, in spite of the 
fact Lhat they contain no text-specific code. So we 11 
spend a little bit of time to see how that’s possible. 
Then we ll see how to create text tracks using the 
standard Movie Toolbox functions. We ll also learn 
how to search and edit text tracks. Toward the end of 
this article, well see how to create chapter tracks and 
HREF tracks. When all is said and done, weil have at 
hand the essential tools that we need to create text 
tracks, keyed text, chapter tracks, and linked text. 
Figure 6 shows the Test menu of this month's sample 
application, named QTText. 
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Tent 


Set Search Tent... 

*T 

Find Tent 

*F 

Edit Current Tent... 


✓ Search Forward 


Search Backward 


✓ lilrap Search 


Be Case Sensitive 


Add Tent Track 

Delete Tent Track 

V Chapter Track 


HREF Track 

_ 


Figure 6 The Test menu of QTText. 


The Edit Mend Revisited 

Let's begin by considering our code for enabling and 
disabling items in the Edit menu. (This might appear to 
have nothing at all to do with text handling, but it is 
actually fairly germane to this topic. Trust me.) Currently, 
when the user clicks in the menu bar to select one of our 
application's menus, our application framework calls the 
QTFrame_AdjustMenus function. (In our Macintosh 
framework, this happens in response to a mouseDown 
event in the inMenuBar window part: in our Windows 
framework, this happens when the MDI frame window 
receives the WMJNITMENU command.) Listing 1 shows Lhe 
code in GTFrame_AdjustMenus that adjusts the Edit menu. 


Listing 1; Adjusting the Edit menu (original version) 


QTFra me _Ad [list M emis 

#if. TARGET_0S_M AC 

myMenu = GetMenuHandle(kEditMenuResID): 

//end if 

if (myMC != NULL) { 

long myFl-ags: 

MCGetControllerlnfo(myMC, fcmyFlags): 

QTE rame_S e tMe unitemState{my M enu, IDM_EDITUND 0„ 

myFIags h mclnfcUndoAvailable ? 
kEnableMenuItem : kDisableMenultem): 

QTF rame_S etMenuItemSta te(myMenu. IDM_EDITCUT. 

myFiags & mcInfoCutAvailable ? 
kEnableMenuItem : kDisableMenultem): 

QTFrame_SetMermItemState(myMenu. IDM_EDITCOFY t 

myFlaga & mclnfoCopyAvailable ? 
kEnableMenuItem : kDisableMenultem): 

QTFrame_SetMenuItemState{myMenu* IDM_EDITPASTE P 

myFlags k meInfoFasteAvaitable ? 
kEnableMenuItem : kDisableMenultem): 

QTFrame_SetMenuItemState(myMenu, IDM_EDITCLEAR. 

myFiags & melnfoClearAvailable 7 
kEnableMenuItem : kDisableMenultem)■ 

QTFrame.SethfenuIternState(myMenu* IDM„EDITSELECTALL. 

myFiags Gr mclnfoEditIngEnabled ? 
kEnableMenuItem : kDisableMenultem) : 

QTFrame_SetMenuItemState(myMenu. IDM_EDITSELECTNONE. 

myFlags 6s mdnfoEditingEnabled 1 
kEnableMenuItem : kDisableMenultem); 

1 else E 

QTFrame_SetMenu!temState (myMenu* I DM., ED IT UNDO. 
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QTE rame_SatMenuIt emSt ate(myMenu, 
QTFrame_5etKemiItem5tate (myMenu p 
QTFrame_SetMemiItem5iate(myMenu* 
QTFrame_SetMemiItemState(myMenu P 
QTFrame^SetMenuItemState(myMenu. 
QTFrame_SetMeuuItemState(myMenu P 
QTFrame_SetMemiItefflState(myMenu. 


IDM_EDITUNDG, 
kDisableMenuItem); 

IDM_EDITCUT * 
kDisableMenuItem): 

IDM_EDITCOPY P 
kDisableMer.uItem) ; 

IDM^EDITPASTE. 
kDisableMenuItem): 

IDM_EDITCLEAR. 
kDlsableMenuItemJ: 

ID M_E DITS EL E C T ALL. 
kDiaableMenuItem); 

IDM_EDITSELECTNQNE. 
kDisableMenuItem); 


There’s nothing particularly complicated here: if 
there is no movie controller associated with the 
frontmost window or there is no frontmost window, 
then we disable all the items in the Edit menu (that’s 
the “else” portion). Otherwise, we call the 
MCGetControlterlnfo function to determine the current 
status of the movie controller and its associated movie, 
MCGetControlterlnfo returns a set of flags that indicate 
which editing operations currently make sense for the 
specified movie controller and its movie. For instance, 
if there is some data available for pasting and editing 
is enabled, then the mclnfoPasteAvailable flag is set in 
the 32-hit long integer returned by MCGetControlterlnfo. 
In this case, our application should enable the Paste 
menu item. Conversely, if either editing is disabled for 
the specified movie or there is nothing to paste, then 
that flag is clear. In that case, the Paste menu item 
should be disabled. We call the function 
QTFrame_SetMenultemState to enable or disable the 
Paste menu item, like this: 


QTFram£_SenMenuItetnST3te(myMenu, 2DM_EDITFASTE T 

myFlags & tocI nfoPasteAvaliable ? 
kEnableMenuItem : kdisahleMenuTtem): 


We’ve already considered QTFrame_SetMenultemState 
in an earlier article (see "QuickTime 101” in MacTech, 
January 2000); it just calls ihe appropriate platform-specific 
function lor enabling or disabling a menu item. 

Emulating QuickTime Player 

So far, so good. But there is a very important 
capability that we still need to add to our sample 
applications, if w r e launch the QuickTime Player 
application, open a movie, make a selection, and then 
hold down the Option key (or t on Windows, both the 
Ctrl and Alt keys) while clicking on the Edit menu, 
wee’ll see something like the menu shown in Figure 7: 


Edit 



Figure 7: The Edit menu of QuickTime Player 
(Option key down). 

Notice that the Paste menu item is now labeled "Add” and 
the Clear menu item is now labeled "Trim”. Similarly, if 
we hold down just the Shift key while clicking on the Edit 
menu, well see the menu shown in Figure 8: 


Edit 



Figure 8 The Edit menu of QuickTime Player 
(Shift key down). 

Now the Paste menu item is labeled "Replace”. Finally, if 
we hold down the Option and the Shift keys (or, on 
Windows, the Ctrl and Ah and Shift keys) while clicking 
on the Edit menu, the Paste menu item will be labeled 
"Add Scaled”, as shown in Figure 9 (For the moment, 
don’t worry about what these renamed menu items 
actually do; we 1 II get to that in the next section.) 


Edit 



Figure 9: The Edit menu of QuickTime Player 
(Shift and Option keys down). 

What’s happening here is that QuickTime Flayer is 
not using MCGetControllerlnfo to do its Edit menu 
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adjusting, at least for the first five menu commands. 
Instead, it’s using the MCSetUpEditMenu function, which is 
specially designed to change the Edit menu item labels in 
the ways just described* depending on which keyboard 
modifier keys the user is holding down, MCSetUpEditMenu 
is declared essentially like this: 

ComponentResuIt HCSettlpEditMenu (MovieControlIer me. 

long modifiers, MenuHandle mh) ; 


MCSetUpEditMenu correctly enables or disables and names 
the first five commands in the Edit menu specified by the 
menu handle mh, as long as those items have the standard 
arrangement (Undo, a separator line, Cut, Copy, Paste, 
and Clear), 

It appears, then, that we can simplify our menu- 
adjusting code and gain the additional behaviors described 
above by using MCSetUpEditMenu ourselves. There are just 
a couple of changes we need to make to supporL 
MCSetUpEditMenu. Primarily, we need to add a parameter 
to our QTFrame AdjustMenus function, so that we can pass 
it the current keyboard modifiers. Henceforth, 
QTFrame_AdjustMenus will be declared like this: 

int QTFrante_AdjustMenus (WindowReference theWindow. 

MenuReference theMesu, long theModifiers); 


Getting the appropriate keyboard modifiers in our 
jVlacintosh code is easy. Whenever we call 
QTFrame_AdjustMenus, either we don't care about the 
modifiers (so we can pass 0L> or we have an event record 
available (so we can pass (long)theEvent->modifiers). 


Getting the Modifier Keys on Windows 

When we call QTFrame_AdjustMenus on Windows, 
however, we need to do some additional work to 
determine which (if any) modifier keys the user is holding 
down when clicking on the Edit menu. Remember that we 
want to pass MCSetUpEditMenu a long integer whose bits 
indicate which modifier keys are active. The “gotcha !s 
here is that these are supposed to be the modifier keys on 
a Macintosh keyboard. MCSetUpEditMenu knows nothing 
about the Alt or Ctrl keys found on Windows keyboards. 
Rather, it's expecting a 32-bit value in which the up or 
down state of the relevant modifier keys is encoded using 
these bits (defined in Events, h): 


lum l 
cmdK&y 
shiftKey 
alphaLock 
optionKey 
controlKey 


1 << cmdiCeyBit. //0x0100 


_ << shiftKeyBit, // 0x0200 
1 << alphaLockBit.//0x0400 
1 << optionKeyBit. 

1 << centrolKeyBlt//Ox 1000 


// 0x0800 


For example, if only the Option key is down, the 
modifiers value should be 0x00000800. Similarly, if both 
the Shift and Control keys are down, the modifiers value 
should be 0x00001200, 
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QuickTime maps the Windows modifier keys to the 

Macintosh modifier keys in this manner: 

* The Windows Alt key is mapped to the Macintosh 
Control key. 

* The Windows Ctrl key is mapped to the Macintosh 
Command key. 

* The Windows Shift key is mapped to the Macintosh 
Shift key. 

* The Windows Caps Lock key is mapped to the 
Macintosh Caps Lock key. 

* The combination of the Windows Alt and Ctrl keys is 
mapped to the Macintosh Option key. 


To help us construct a Mac-style modifiers long word, 
well add these constants and compiler macros to the File 

WinFrameworkh: 


//define VK_MAC_CONTROLKEY 
//define VK_M AC_ C OHM A N DK E Y 
//define VK_MAC_SHIFTKEY 
//define VK_M AC„ CAPS KEY 


VK_HENU 

VK_CGNTROL 

VK_SHIFT 

VK_CAFITAL 


myModif let's |* optionKey: 
else if CQTFrame_IsCommandKeyDowtt(myKeyState]) 
myModifiers J- cisdKey; 

else if (QTFrame_IsCoTitrDlKeyDown (myKeyState) ) 
myModifiers |- controlKey: 

if (QTFrame_IsShiftKeyDown(myKeyState)) 
myModifiers l~ shiftKey: 
if (QTFrame_IsAlphaLockKeyDown (myKeyState)) 
myModifiers |= alphaLock; 


return(myModifiers); 
l 


So, on Windows, we are now able to pass the correct 
set of modifier flags to MC SetUp EditIVtenu. But what do we 
pass for the third parameter, which on MacOS is a menu 
handle for the Edit menu? The answer, k turns out, ts that 
we'll pass the value NULL. The reason for this is that on 
Windows we access our menus using a value of type 
HMENU, nol Menu Handle, This means, however, that on 
Windows we cannot depend on MCSetUpEditMenu to 
either highlight or rename the items in the Edit menu. For 
that, well have to write our own code. 


//define QTFrajne_lBCcntrolKeyDown( theKeyState) 

(theKeyState[VK_HAC_COMTROLKEY] fir OxBO ? 1 : 0) 
//define QTFrame_IsCommandKeyDown(theKeyState) 

(theKeyState[VK_MAC_COMMANDKZY| & 0x80 ? 1 : 0) 
//define QTFrame_laShif tKeyDown (theKeyState) 

(theKeyStateiVK_MAC_SHXFTKEYj & 0x30 ? 1 : 0) 
//define QTFrarae_IsAlphaLockKeyDovn(theKeyState) 

(theKeyState[VK_MAC_CAFSKEY] & 0x30 71:0) 
//define QTFrame_IeOptionKeyDown (theKeyState) 

(QTFrame_IsControlKeyDown(theKeyState)) && 
CQTFraiDe_IsGommandKeyDown (theKeyState)) 


On Windows, a key slate array (represented by the 
argument theKeyState in these macros) is a 256-byte array 
that contains information about each of the 256 virtual- 
key codes. If a key is down, then the high-order hit 
(0x80) of the corresponding element of this array will he 
set. For instance, if the All key is down, then the high- 
order hit of the array element whose index is 0x12 will be 
set. (The virtual-key code for the Alt key is VK_MENU, 
which is defined as 0x12 in the file Winuser.hJ 

We can fill a key state array with the current values 
by calling the GetKeyboardState function. Then all we 
need Lo do is inspect the Windows modifier keys that are 
of interest to us and construct a Mac-style modifiers value 
that encodes that information. When we need to call 
GTFrame AdjustMenus, we can get the current set of 
modifier keys by calling GTFrame_GetKeyboardModifiers, 
defined in Listing 2. 

Listing 2; Getting the Windows keyboard modifier keys 


QTFr.i m c_Ge I Ke y h oa rd Modi fit rs 
static long QTFrame_GetKeyboardModifiers (void) 

[ 

long myModifiers = 0L; 

BYTE myKeyState[256]; 

if (GetKeyboardState(fiimyKeyState[0] )) t 
if (QTFrame_IsOptionKeyDown(myKeyState)) 


Renaming the Edit Menu hems on Windows 

At this point, you might be wondering why weTe 
bothering to call MCSetUpEditMenu on Windows, if it isn't 
going to help us with highlighting or renaming the items 
in the Edit menu. The answer is that MCSetUpEditMenu 
does more than simply enable or disable menu items and 
rename them to match the state of the active modifier 
keys, MCSetUpEditMenu also sets some flags maintained 
internally by the movie controller that affect the 
operation of subsequent editing commands. For instance, 
when we call MC Paste, it looks at those flags to 
determine whether it should paste, or replace, or add, or 
add scaled. In other words, if we don’t call 
MCSetUpEditMenu, all our editing operations wall just be 
the default undo, cut, copy, paste, and clear operations. 

On Windows, we still have two tasks left to handle. 
First, we need to perform our own Edit menu item 
enabling and disabling. We already have code for this 
(see Listing 1 again), so well just conditionalize that code 
to be executed under Windows but not under MacOS. 
Second, we need to find a way to rename the Edit menu 
items according to the current state of the modifier keys. 
This task is actually relatively easy, since QuickTime 
provides the MCGetMenuString function, which we can 
use to retrieve the label for a particular menu item, given 
a set of modifier keys, Suppose, for instance, that we 
execute this line of code (here, myString is of type 
Str255): 

MCGetMenuString(myHC, optionKey. rocMemiPaste, myString): 

If MCGetMenuString completes successfully, then myString 
will hold the string “Add*. All we need to do then is insert 
that string into our Windows Edit menu. The function 
GTFrame^ConvertMacToWinMenultemLabei. defined in 
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Listing 3, handles all of this for us. 

Listing 3: Renaming a Windows Edit menu item 


QTFrame_Con ve rr M acToWi n M enu l te mLabt l 

void, QTFrame_CouvertMacToWiriMeiHiItemLabel [ 

MovieController theMC, MenuReference CheWinMeriu. 
long theModiflers, UIntl6 thettenultem) 

l 

Str255 myString; 

char OnyLabelText = MULL: 

char ‘myBegiriText = MILL: 

char ‘myFinalText = NULL; 

short myLabelSize = 0: 

// go tiie appropriate label for die specified item and keyboard modifier 

MCGetMemiString(theMC. theModifiera, 

MENU_ITEH CtheMenuItem). myString); 

switch (theMemiltem) f 
case IMLEDITtINDO: 

myBeginText = kAmpersandText: 
myFinalText = kWinUadoAccelerator: 
break: 

case IDtLEDITPASTE: 
myBeginText “ ; 

myFinalText = kWinPasteAccelerator: 

case IDM_EDITCLEAR: 

myBeginText - kAmpersandText; 
myFinalText = kWinGlearAccelerator: 
break: 
default: 

// currently, only the Undo. Paste, and Clear items are modified by 
// MCSetUpEditlWenu, so that T s all well handle here 

return; 

1 


myLabelSize = strlen(myBeginText) + myStringfO] + 

strlen(myFinalText) + 1; 

myLabelText = malloc(myLabelSize); 

if (myLabelText =- NULL) 
return: 

BlockMove (myBeginText, myLabelText * strlen (myBeginText)); 

BiockMove (fcmyString [ 1 ] , myLabelText + strIen (myBeginText), 
myString[0]); 

BlockMove(myFinalText* myLabelText + strlen(myEeginText) + 
myString[0], strlen(myFinalText)); 

myLabelText[myLabelSize ■ 1] = *\G* ; 

QTFraroe^SetMenuItemLabel(theWinMenu t theMenuItem h 

myLabelText): 

free(myLabelText); 

I 

QTFrame_ConvertMacToWFnMenultemLabel also adds the 
ampersand (&) to the beginning of several of the Edit menu 
items (so that the first letter is underlined) and the appropriate 
keyboard accelerator label to the end of all of them. 

Putting it All Together 

We're finally ready ro put all these pieces together Listing 4 
shows our revised version of Listing L When no movie controller 
is available, we disable all the Edit menu items in exactly the 
same manner we did in our earlier version. And for the "Select 
All 1 ' and “Select None” items, we call MCGetControllerlnfo and 
QTFrame_SetMenu ItemState. just like lyefore. But for the five 
standard Edit menu commands, we now call MCSetUpEditMenu 
on both Mac and Windows. In addition, on Windows we need 














to do all menu item enabling and disabling ourselves, and we 
need to update the menu item labels, using our function 

QTFrame_ConvertMacToWinMenu!temLabel. 

Listing 4: Adjusting the Edit menu (revised version) 


QTFrame_Adj u st Menu $ 

#if TARGET_OS_MAC 

my Menu ~ GetMenuHandl e (kEd i tMenuResI D); 

fendif 

if (myMC = NULL) 1 

// if there; is no movie controller, disable ail the Edit menu items 
GIFrame_SetMenuIt emStat e{ntyMenu, IDM_EDITUNDO, 

kDisableMenuItem) ; 

QTFrame_Se tMenuItemState (myMenu . IDM^EDITCUT. 

kDisableMenuItem); 

QTFrame._SetMermItemState (myMenu. IDM_EDITCOFY f 

kDisableMenuItem); 

QTF r&me_Se tMenuIt emSt at e(myMenu. IDM_EDITPA STE * 

kDisableMenuItem) ; 

QTFrame_SetMenuItem3tate (myMenu. IDM_EDITCLEAR. 

kDisableMenuItem): 

QTF I: ame_S e tMenuI t emSt at e (my Menu. IDM_EDITSELECT ALL. 

kDisableMenuItem); 

QTF r ame_S etMenu11 emSt at e{myMenu, IDM_EDITSELECTNOME. 

kDisableMenuItem); 

) else l 

MCGetCentro Her Info (myMC * kmyFIags); 

QTFrame_EetMemiltemState (myMenu, IDM_EDITSELECTALL, 
my Flags & me Inf oEditingEnabled 7 
kEnableMenuItem : kDisableMenuItem) j 
QTF c ame„Se tMenuI t emS t at e (myMenu. IT)M_EDI TS ELECTNONE , 
myFlags & mcInfoEditingEnabied ? 
kEnableMenuItem : kDisableMenuItem); 

#if TARGETJDSJ4A.C 

MCSetUpEditMenuCmyMC. theModifiers. myMenu); 

^ end if 

#if TARGET_0S_WIN3 2 

MCSetUpEditMenu (myMC, theModifiers. NULL); 

GTFrame_SetMenuItemState(myMenu , TDM EDITUNDO, 

myFlags & meInfoUndoAvaiiable ? 
kEnableMenuItem : kDisableMemiltem): 

QTF rame^etMenu It emState (myMenu, IDM EDXTCUT, 

myFlags & meInfoCutAvailable 7 
kEnableMenuItem : kDisableMenuItem); 
QTFrame_SetMenuItemState(myMenu, IDM_EDITCOPY. 

myFlags & meInfoCopyAvailable 7 
kEnableMenuItem : kDisableMenuTtern) ; 

QTFrame_SetMenuItemState [myMenu , IDM_ED1TPASTE. 

myFlags & mclttfeFafite Avail able ? 
kEnableMenuItem : kDisableMemiltem); 

QTF t ame_S etMenuIt emStat e {myMe nu , IDM_ED ITCLEAE. 

myFlags & meInfoClearAvailable ? 
kEnableMenuItem : kDisableMenuItem): 

QTF r ame_Conve rtMa cTg Wi nM e nul t emLabe 1 

[myMC. myMenu. theModifiers, IDM_^DITUNDO): 

QTF rame_GonvertMacToWlnMenuItemLabel 

(myMC, myMenu, theModifiers. IDM_EDITCUT): 

QTF r ame_Conv e rtMacToWinMenu11 emLab e1 

(myMC. myMenu, theModifiers, IDM_EOITCQPY); 

QTF r ame_Con ve r tMa c ToW i nMen ill temLab e1 

(myMC. myMenu, theModifiers, 1DM_EDITFASTE); 

QTF rarae_Conve t tMa cTaWinMenuItemLabel 

(myMC, myMenu, theModifiers. IDM_EDITCLEAR); 

#endif 

1 


There is one final modification that we need to make 
to our Windows source code. Apparently, on Windows, 
calling the MCIsP[ayerEvent function has the nasty side- 


effect of clearing the movie controller flags that store the 
current modifier key settings. So we need to make sure 
that we do not call MClsPlayerEvent if we are about to 
execute an editing command. We can do this by adding 
the condition (theMessage 1= WM_COMMAND) in the 
movie window procedure QTFrame_MovfeWndProc. See 
the version of WinFrameworkx included in this month's 
code for the exact placement of this fix. 

Text Importing 

Suppose now that we’ve implemented all the changes 
described in the previous section. Let’s see what all this 
work has bought us. 

Importing Text from the Clipboard 

Open a movie with a video track, perhaps even the 
penguin movie we created in an earlier article. Select part 
or all of the movie. Then switch to some application that 
can handle text; in that application, select some text and 
copy it. Then return to our upgraded application and 
execute the “Add Scaled" command in the Edit menu (that 
is, choose Paste while holding down the Shift and Option 
keys on the Mac, or the Shift and Ctrl and Alt keys on 
Windows). Voila — we've just added a text track to our 
movie, positioned below the video track. 

Keep in mind that our upgraded sample applications 
contain absolutely no special code for handling text 
media. So how did we manage to create a text track so 
effortlessly? The answer is that MCPaste looks to see what 
kind of data it s being asked to insert into the open 
movie. If it's a segment of a movie, then MCPaste just 
inserts the data as we’d expect. But if the data isn't movie 
data, MCPaste looks around for a QuickTime component 
that can import that kind of data as a movie. In other 
words, MCPaste goes looking for a suitable movie import 
component. In this case, it finds the text movie import 
component (component type MovielmportType and 
subtype TextMediaType), which inspects the current 
modifier flags cached by the movie controller and 
performs the operation corresponding to those flags. 

* If none of the relevant modifier Hags is set, the text 
movie importer pastes the text data at the current 
position in the movie. If a text track already exists in 
the movie, the pasted text is inserted into that track 
and inherits all the spatial and visual characteristics of 
that track. But if no text track exists in the movie, the 
text movie importer creates a new track that has the 
same size and position as the current movie box. The 
pasted text is given a default duration of two seconds. 

* If only the Shift modifier flag is set, then MCPaste 
performs a Replace operation. If the movie has a non¬ 
empty selection, the pasted text replaces the current 
selection; otherwise, if there is no selection, the pasted 
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text replaces the entire movie. In both cases, the 
duration of the pasted text sample is the default two 
seconds. 

* If only the Option modifier Hag is set T then MCPaste 
performs an Add operation; the text track is positioned 
below the existing video track, with a height that 
accommodates the pasted text (this is called adding in 
parallel}' The duration of the pasted text sample is the 
default two seconds. 

• If both the Shift modifier flag and the Option modifier 
flag are set, then MCPaste performs an Add Scaled 
operation; a text track is added in parallel for the 
duration of the current selection. If there Is no 
selection, then the text track is added in parallel for 
the duration of the entire movie. 

On Macintosh operating systems only, holding down 
the Control key and any other combination of modifier 
keys while selecting Paste in the Edit menu causes the 
text movie importer to display the text import settings 
dialog box, shown in Figure 10 . This dialog box allows 
the user to configure some settings of the pasted text. 



Figure 10: The text import settings dialog box 

Importing Text from a File 

The text movie importer can also import text stored 
in a file, and indeed provides some additional capabilities 
that are not available when pasting text from the scrap. If 
we open a text file using any of our sample applications, 
the text importer creates a movie that has a text sample 
for every paragraph of text in the file. Each text sample 
will have the standard default duration of two seconds 


FUNNELWEB 





>) 




X 


/ 


Better, Stronger, Faster 


Intelligent Web site Monitoring and Analysis Software 


Speed, intuitive user interface, accuracy and in-depth analysis have always made 
Funnel Web the intelligent choice for Web site analysis. 

Now includes pdf output, incremental analysis, cluster analysis and streaming media reports. 






























and will be drawn in the default text font, which is 
dependent upon the operating system. 

Note that, since we're importing a file and not pasting 
data from the system scrap, our existing sample 
applications will exhibit this behavior, whether or not 
we've applied the changes described in the previous 
section. This is just another case of NewMovieFromFile 
detecting that the file we T ve asked it to process is not a 
QuickTime movie file and then looking around for a 
suitable movie importer to handle that data. (See “Quick on 
the Draw" in MacTech, April 2000 for more details on this.) 

The text importer recognizes a large number of text 
descriptors that modify the default characteristics of the 
imported text. Suppose that we open a text file that 
contains these lines of text: 

!QTtext \ 

{font:Tektoni)(plain \ (size:18) 

itextColor: 0. 0 , 01 [backColor; 65535. 65535, O'I 
1 justify: center ) i timeScale : 600 \ [width: 240] I height: 40 j 
l tisueS tamps: absolute) l language : 0 I I text Encoding: 0) 

{ shrinkTextBox; on) 

[ 00 : 00 : 00 , 000 ] 

ItextBox: 10, 0* 30. 240fWe forgot to seedE 
[ 00 : 00 : 01 . 000 ] 

ItextEox: 10. 0. 30, 240>D‘0h! 

[ 00 : 00 : 01 . 100 ] 

ItextBox: 10, 20, 30. 240]D p 0ht 
[ 00 : 00 : 01 . 200 ] 

ItextBox: 10. 40, 30, 240 ID‘OhE 
[00:00:01*300] 

ItextBox: 10, 60 t 30, 240)D'Oht 
[00:00:01.400] 

ItextBox: 10, 80, 30. ZiOlD'Qh! 

[00:00:01*500] 

The text importer inspects the text descriptors found 
within the braces and creates the movie whose first frame 
is shown in Figure 11. 


□Jjjj 

^^===^seed.ttft= = 

We forgot to seed! 


1 


Figure 11: The imported movie. 


Unfortunately, we don’t have space to investigate text 
descriptors in more detail here. For complete 
documentation on using the available text descriptors, see 
the sources mentioned at the end of this article. 

Text Tracks 

As we’ve seen, the text movie importer provides our 
applications with a good deal of text-handling power at a 
very small cost. In fact, we didn’t have to do anything at all 
to allow our applications to import text files, and we simply 
had to upgrade our Edit menu adjusting code to allow them 
to handle pasted text. But we still need to see how to create 


text tracks directly, without relying on the text movie 
importer. After all, we want to be able to work with text data 
that’s not read from a file or from the system scrap. 


Adding Text Media Samples 

By this point in this series of articles, 
programmatically adding a track to a movie should be 
old-hat {since we’ve done this two or three times so far). 
We just need to call NewMovieTrack and NewTrackMedia to 
create a new track and media, call Begin Media Edits to 
begin a media-editing session, call AddMediaSample to 
add samples to the media, call EndMediaEdlts to end the 
media-editing session, and then call InsertMedialntoTrack 
to insert the newly-edited media into the track. For any 
new kind of media that we encounter, we really need to 
ask only two questions: (1) what is the format of the data 
in the media samples? And, (2) what is the structure of the 
sample description that we need to pass to 
AddMediaSample? 

For a text track, the media sample data is just the string 
of characters in the text itself, preceded by a 16-bit length 
Held that specifies the number of characters in that string. 
And the appropriate sample description is a text description 
structure, defined by the TextDescription data type: 

struct TextDescription [ 
long 
long 
long 
short 
short 
long 
long 

RGBColor 
Kect 

Sc rpSTElement 
char 

1 : 


descSize: 
dataFormat; 
resvdi; 
resvd2; 
dataRefIndex: 
displayFlags; 
textJust ification; 
bgColor; 

def aiil tTextBox; 
defaultstyle; 
defaultFontName[1 ] : 


The first five fields, of course, are the first five fields 
of the generic SampleDescription structure. The remaining 
fields are specific to text media. The display Flags field 
holds a set of flags that indicate how the text is to be 
displayed. These flags allow us to specify various 
scrolling options and other positioning options. For the 
moment, well be content to specify the dfClipToTextBox 
flag, which restricts any updates caused by changes in the 
text track lo the area occupied by the text track. (By all 
means, however, you should experiment with some of the 
scrolling options, like dfScroflln and dfScrollOut) 

The defauItTextBox field specifies the location of the 
box that encloses the text. The rectangle is interpreted as 
relative to the upper-left corner of the text track rectangle. 
The textJustification field contains a value that specifies 
how the text is to be justified within the text box. The 
Movie Toolbox recognizes these constants for specifying 
a text justification (defined in the header file TextEdit, h): 

enum [ 

teFlushDefault “ 0, 

teGenter “ 1* 
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teFlushRight = -1, 

teFlushLeft = -2 

I; 

The bgColor field specifies the background color of 
the text box. The default text color is black. Note that 
because we call MewHandteClear to allocate a 
TextOescription structure, the default background color 
will also be black unless we change the values in the 
bgColor field. To make the Lext visible, well set the 
background color to white, like this: 

RGBColor myBGColor - IOxffff, Oxffff, OxffffI; 

(**mySajnpleDesc) ,bgColor - inyEGColor; 

The last two fields of the TextDescription structure 
indicate the desired text style and font. We’ll ignore Lhese 
fields here. 

Listing 5 shows a segment of the QTText_AddTextTrack 
function, which we use to add a new text track to a movie. 
As you can see, it allocates a handle to a text description 
structure, fills in some of the fields with appropriate values, 
calls PtrToHand and PtrAndHand to create the text media 
sample, and then calls AddMediaSample to add the text 
media sample to the text media. 

Listing 5: Adding a text media sample 

QTTcxt _ Ad d Ilex tTrack 

TexiDesctiptionHatidle myS ampleDesc = NULL; 

Handle mySample - NULL; 

Ulutlfi myLength; 

RGBColor myBGColor = tOxffff, Oxffff. Oxffffh 


mySampleDesc = (TextDesctiptionHandle) 

NewHandleCleartsizeof(TextDescription)J; 
if [mySampleDesc = NULL) 
goto bail: 

(* *mySampleDesc},descSize = sizeof (TextDescription): 

(* *TnySampleDesc) . dataPormat ™ TextMediaType; 
[**tnySampleDesc),displayFlag3 = dfClipToTextBox; 
C**inySarapleDesc).textJustification = teCentert 
(* * mySampleDesc).defaultTextEox = myBounds: 

(*tmySampleDeschbgColor = myBGColor; 

myLe n gt h = End i anti 16_Nto B (my S amp 1 eText [ 0 ]) ; 

// creme the text media sample: a lb-hit length word followed by the text 

myErr = PtrToHand(frmyLength* fenySample, slzeof(myLength)); 
if (myErr = noEtr) I 

myErr = PtrAndHand ((Ptr) E&mySampleText [1]), mySample, 

mySampleText [Oj); 

if (myErr = noErr) 

AddXediaSample( myMedia, mySample, 0, 

GetHandl-eSize[mySample) 
myText S amp1eDu r ation. 

(SampleDesc riptionHandle)mySampleDesc. 

1, 0., NULL); 

Di Bp os eHand 1 e (my S amp 1 e); 

\ 

DisposeHandleC(Handle)mySampleDesc); 

The Movie Toolbox also provides the 
TextMediaAddTextSampte function, which allows us to 
simplify this process significantly. Indeed, all of the work 
done in Listing 5 can be accomplished w T ith this single 
line of code; 

myErr « TextMediaAddTextSample[ 
myHandler, 

(Ptr)(^mySampleText[1]) , 
mySampleText[0]. 

0, 

0 , 

0 . 

NULL* 

NULL* 
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teCenter* 

&myBounds, 
dfClipToTextBox * 

0. 

0 . 

0 * 

NULL, 

myTextSampleDuration. 

NULL): 

Text MediaAddTextSam pie takes seventeen parameters 
{count 'em!), which is probably some kind of record for a 
Movie Toolbox function. The payoff For this complexity is 
Lhat it allows us to dispense with allocating a sample 
description or a text sample and with worrying about 
endian issues. Instead, we pass it the text media handler, 
myHandler (which we can obtain by calling 
GetMediaHandler on the text media), the text, and a 
handful of other parameters describing the desired 
characteristics of the text track. 

Positioning a Text Track 

When we create a text track, using either 
AddMediaSample or TextMediaAddTextSampla, we need to 
specify the size and location of the text track, QTText 
determines the width of the new text track by calling 
GetTrackDImensions on the first video track in the movie: 

GetTrackDimensions(myTypeTrack, kmyWidth* &myHeight): 


SetTrackEnabled(rayTextTrack. true); 

We can hide the text track by passing false to disable it. Even 
if a text track is disabled, however, it can still be of use in a 
movie. For instance, we can search for text in a disabled text 
track, and tire movie controller scans all text tracks, 
including disabled ones, when looking for chapter tracks. 
Similarly, the QuickTime Plug-In searches all text tracks, 
even disabled ones, when looking for an HREF track. 
Indeed, chapter tracks and HREF tracks are usually disabled. 

Creating a Text Track 

Listing 6 shows our complete function 
GTText_AddTextTrack for adding a text track to a movie. 
The parameter theStrings is an array of C strings; each 
element of that array is the text for a specific text sample. 
The parameter theFrames ls an array of integers; each 
element of that array indicates how many video frames a 
text sample is to span. The sum of all the values in 
theFrames should equal the total number of frames in the 
video track. Finally, the isChapterTrack parameter 
indicates whether the new text track is to be a chapter 
track; if isChapterTrack is true, then the new text track is 
attached as a chapter track to the first track whose type is 
specified by the theType parameter. 


QTText uses the constant kTextTrackHeight (defined as 20 
pixels) as the height of the text track. 

For below-the-video text, we can specify the position 
of the text track by setting the track matrix, like this: 

GetTrackMatrix(myTextTrack. &myMatrix ]I 
TranelateMatrix(&myMatrix. 0, myHeight): 
SetTraekMatrlx(myTextTrack. &myMatrix}: 


All we’ve done here is translate Lhe matrix downward by 
the height of the video track (myHeight). For text that 
overlays a video track, of course, well need to reset the 
matrix in some other way. 

Enabling or Disabling a Text Track 

Each track in a QuickTime movie is either enabled or 
disabled. By default, a newly-created track is enabled, in 
which case its media data directly contributes to the overall 
user experience. For example, an enabled video track is 
visible (unless of course it's completely covered by other 
enabled tracks), and an enabled audio track is audible. 
Most other media types, including text media, are visual 
media types, so once again being enabled means being 
visible. On the flip side, a disabled track does not usually 
contribute audible or visible data to the movie. Disabling a 
track is a quick and easy way to hide or mute it. 

We can enable or disable a track by calling the 
SetTrackEnabled function, passing it a track identifier and 
a Boolean value that indicates whether to enable (true) or 
disable (false) the specified track. When we create a text 
track, we make sure it T s visible by enabling it, like this: 


Listing 6; Adding a text track 


QTText _ AddText Track 


Track QTText_AddTextTrack (Movie tbeMovie, 

char ‘theStrings[], short theFrames[1, short theNumFrames, 
QSType theType, Boolean isChapterTrack) 

I 


Track 

Track 

Media 

MediaHandler 

TimeScale 

MatrixHeccrd 

Fixed 

Fixed 

OSErr 


myTypeTrack = NULL: 
my TextTrack = NULL: 
myMedia " NULL; 
myHandler - NULL; 
myTimeScale; 
myMatrix: 
myWidth: 
myHeight: 
myErr “ noErr; 


//get the (first) track of the specified type; 

// til is track determines the width of the new text track 

// and (if isChapterTrack is true) Is the target of the new chapter track 

myTypeTrack = GetMovielndTrackType (theMovie, 1. 

theType* movieTrackMediaType); 
if (myTypeTrack *= NULL) 
goto bail: 

// get the dimensions of die toilet track 

GetTrackDimensions(myTypeTrack. fcmyWidth, kmyHeigbt); 
myTimeScale = GetMediaTimeScale 

(GetTrackMedia (myTypeTrack)); 


// create the text track and media 

myTextTrack = NevMovieTrack(theMovie, nryWidth, 

FIxRatio(kTextTrackHeight. 1), kNoVolurae); 
if (myTextTrack = NULL) 
goto bail: 

myMedia = NewTrackMedia{snyTextTrack t TextMediaType, 
my Time Scale. NULL. 0); 
if (myMedia = NULL) 
goto bail; 
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myHandler - GetMediaHandler (myMedia); 
if (myHandler — MULL) 
goto bail; 

// figure out the text track geometry 

Ge tTrac kMa t rix(myTextTrack * &myMatrix); 

TranslateMatrixC&iriy Matrix, 0 t myEeight); 

SetTrackMatrix(myTextTrack T &myMat:rix) : 
SetTrackEtiabled (myTextTrack* true); 

// edii the track media 
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San Francisco 


myErr = BeginMediaEditslmyMedia); 

If CmyErr = noErrJ I 

Keen myBounds; 

short myIndex; 

TimeValue myTypeSampleDuration 5 

TimeRecord myTimeRec; 

nryBounds. top = 0; 

myBouads.left = 0; 

myBounds,right = Fix2Ltmg(myWidth); 

myBounds.bottom = FixSLeng{myHeight); 

//determine the duration of a sample in the track of the specified type 

myTypeSampleDuration = 

QTUtils_GetFrameDuration CmyTypeTrack) : 


fo r (my Index ” 0; my Index < theNumFrames; mylndex++) I 
TimeValue my 1 Text Samp ieDti rat ion: 

Str255 my Samp leT ext; 

myTextSampleDuration — myTypeSampleDuration * 

theFrames[myIndex]; 

// set die time scale of the media to that of the movie 

myTimeRec.value,lo " myTextSampleDuration; 
myTimeRec.value*hi = 0: 

myTimeRec.scale = GetKovieTimeScale(theMovie); 
ConvertTimeScale (kmyTimeRec, 

GetMediaTimeScale(myMedia)): 
myTextSampleDuration = myTimeRec*value*lo; 

QTTex t_CopyC S t ringTo Pa s c a1(theS t rings[myIndex]. 

mySamplelext) ; 

// listing 5 omitted at this point for space reasons 

// write out the new data to tlx* media 

myErr = TextMediaAddTextSample( 
tnyfiandler, 

(Ptr)(&mySampleText[1]), 
mySamplelext[0]. 

0* 

0 , 

0 * 

NULL, 

NULL. 
teCenter. 

&myBounda * 
dfClipToText Box * 

0* 

0* 

0, 

NULL. 

myTextSampleDuration* 

NULL); 


myErr = EndMediaEdits(myKedia); 
if (myErr t- noErr) 
goto bail: 

// insert the text media into die text track 

myErr = InsertMedialntoTrack (myTextTrack, 0. 0, 

GetMediaDuration (myMedia). fixed 1); 

If (myErr != noErr) 
goto bail; 

// set the text handling procedure 
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TextMediaSetTextProc (myHandler, gTextProcUPP, 
Ciong)QTFrame_GetWindovObjectFromFrontWlndowO) ; 

// if desired, set the new text track as a chapter track for the track of the specified type 

if (isChapterTrack) 

AddTrackReference (myTypeTrack * myTextTrack, 

kTrackReferenceChapterList» NULL}; 

bail; 

return (myText Track); 

) 

For the moment, you can ignore the calls to 
TextMediaSetTextProc and AddTrackReference, We’ll explain 
them a little later. 

Text Searching 

The Movie Toolbox provides several functions that 
we can use to search for a specific word or series of 
words in a text track. If we are interested in simply 
finding out where in a text track the next occurrence of a 
string is located, we can use the TextMediaFindNextText 
function, like this: 

myTimeValue = GetMovieTimefmyMovie, NULL}; 
myErr D TextMediaFindNextText E myHand ler , 

CFtr)f&theText[1] )* 
theText[0] T 
myFlags h 
myTimeValue. 
firm y Found Time. 

SrmyFoundDura tion, 

firgOffset) ; 

The first parameter, myHandler, is the text media handler 
associated with the text track. The second and third 
parameters specify the text to be searched for and the 
length of that text; here we're supposing that the text is 
contained in the variable theText, which is a Pascal string. 
The fourth parameter is a set of search flags, which 
indicate how TextMediaFindNextText is to search for the 
specified text. These flags are defined: 

enucn ( 

findTextEdgeOK 
findTextCaaeSensitive 
findTextReverseSearch 
findTextWrapArQund 
findTextUseOffset 

k 

These constants are pretty much self-explanatory, except 
for the first and the last. If findTextEdgeOK is set tn the 
search flags, then TextMediaFindNextText will match text 
beginning at the movie time specified by Lhe fifth 
parameter; otherwise, the text must occur in some later 
(or earlier, if findTextReverseSearch is set) sample. If 
findTextllseOffset is set, then TextMediaFindNextText will 
search beginning at the offset specified by the last 
parameter. This allows us to find separate occurrences of 
the search text in a single text sample. 

Our QTText sample application maintains a couple of 
global variables that keep track of the kind of search the 


user wants to perform. Well use those variables to set our 
search Hags like this: 

myFlags = findTextUseOffset; 
if (IgSearchForward) 

myFlags |= findTextReverseSearch: 
if (gSearchWrap) 

myFlags |= findTextWrapAround: 
if (gSearchVithCase) 

myFlags |= findTextCaseSensitive: 

If TextMediaFindNextText finds the text specified by the 
second and third parameters in some text sample, it returns 
the movie time of the beginning of that sample in the sixth 
parameter (here, &myFoundTime). it also returns the 
duration of that sample in the seventh parameter and, in the 
last parameter, the byte offset (from the beginning of the 
text portion of that sample) of the first character of that text. 

Typically, we don't just want to find out where some 
text begins; we also want to advance Lhe movie to that 
point and highlight the found text. We can use the 
MC Do Action function with the mcActionGoToTime action to 
set the current movie time to the time returned to us by 
TextMediaFindNextText, like so; 

myNewTime.value.hi = 0: 
royNewTime.value.lo - myFoundTime; 
myNewTirae,scale “ GetMovieTimeScaleCmyMovie): 
myNewTime.base - NULL: 

// gt> Lo the found text 

MCDoAction (myMC, mcActionGoToTime . &myNewTime) : 

And we can use the TextMediaFiniteTextSampie function to 
highlight the selected text: 

myColor.red - myColor.green = myColor.blue = 0x8000? //grey 
TextMediaHi i 11eTex t Sarple (mytfandl er, iiyFoundTime, gOffset, 
gOffset + CheTcxtfO], knyCalor); 

Once again, however, the Movie Toolbox provides a 
function that greatly simplifies our work here. The 
Movie Sea rchText function, introduced in QuickTime 
version 2.0, finds the text, sets the movie time to the 
beginning of the text sample containing that text, and 
highlights the found text in that sample. So we can 
replace all the code we’ve encountered so far in this 
section with this single line of code: 

myErr ” MovieSearchText ( myMovie, 

(Ptr)(ktheText [1])* 
theText[ Dj * 
myFlags, 

NULL, 

kinyTiineValue, 

&gOffget); 

When we call MovleSearchText, we pass in the movie to 
search, the search text and search text length, a set of flags, 
the first text track to search, and the movie time at which 
to start the search. The set of flags can include any of the 
search flags listed above, as well as any of these additional 
flags that are specific to the MovieSearchText function: 

eiium { 

searchTextDontGoToFoundTiiiie ~ 1L << 16. 


“ 1 « 0, 

= 1 « 1. 
- 1 << 2, 
® 1 « 3. 

= 1 « 4 
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// Like most Mac developers, 

// I easily spend 12 hours a day 

// staring at line after line of C++ code in tiny, 9 point Monaco. 

// Sometimes it makes my eyes feel like they’re on fire. 

I 

So the last thing I need is some 
fuzzy monitor that adds to my headaches. 

I 



/****** begin excitement ******/ 

// That's why I'm so jazzed about this SGI monitor. 

// Its ultra-high resolution = 1600 x 1024 and dpi = no, 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
Jf perfect for poring through lines of code. 

// At first, I was amazed at the clarity, the fine details that emerged. 

i 

It wa <i tike teeing thingt for the firtt time. 

\ 

H Later, though, i learned to appreciate the wide aspect ratio |= 16:10 1 , 
// with a generous 17.3 inches of viewing area. SGI’s 1600 SW 
// lets me have all my documents viewable at once, and it’s 
// a flat panel so it fits on my desk with room to spare. 


H From the moment I saw this thing I was hooked. You wilt be, too, 

i 

Especially when you find out 
how affordable it is. 

// Check it out 

/****** end excitement ******/ 



m/flatpan 


fol time in 7 months ttiai he's been seen during the day. 
pi am registered trademarks of Silicon Graphics, Inc. 
irmatmiT, visit our website or call I-B&0-5GI-7573. 
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searchTextDontHiliteFoundText 
searchTextGneTrackOnly 
s earchTextEnabledTracksOnly 


= 1L « 17 * 
= 1L << IS, 

= XL « 19 


Including cither of the first two flags, 
searchTextDontGoTo Fou n dTi me and sea rchTextDo ntH i I ite FoundText, 
allows us to override the default “go-to-and-highlight’ 5 behavior 
of MovieSea rchText :. The next two flags modify the track- 
searching behavior If we pass a track identifier in the fifth 
parameter, then MovieSea rchText will search only that track if the 
searchTextOneTrackOnly flag is set; otherwise, it will search all text 
tracks in the specified movie, starting with that track. We can 
restrict the search to ail enabled text tracks by setting the 
searchTextEnabledTracksOnly Hag, 

If MovieSearchText finds the specified text, it returns 
the movie time of the text sample in which the text was 
lotind and the byte offset within 13 1 ai sailipIe of the ft>und 
text, it also returns the track identifier of the track 
containing the text sample, unless the track parameter 
was set to NULL on input. 

Listing 7 contains the definition of our function 
GTText_FindText s which we use to search for text. As you 
can see, it uses either the TextMediaFindNextText function 
or the MovieSearchText function, depending on the value 
of tlic compiler flag USE_MQVEESEARGHTEXT, 


Listing h Finding some text 

QTTm„Ftmnex t 


if (rayEandler 3= NULL) [ 

TimeValue luyFoundTiiue, myFoundDuration; 

TimeRe cord myNewTime; 

RGBColor myColor: 

myColor.red = myColor.green - myColor.blue — 0x8000://grCy 

U starch for the specified text 

myErr = TextMediaFindNextText(myHandler, 

(Ptr) (fitheText [ L] } . theText [0] . myFlags, myTimeValue, 
£imyFoundTime T &my Foun&Dura t i on, & gOf f s et): 
if (rnyFoundTime 1= -1) I 

// convert the Time Value to alTmeRecord 

myNewTime.value.hi » 0; 

my NewTime. val ue«. lo = myFoundTime: 

myNewTime* scale = GetMoviaTimeScale(myMovie) : 

myNewTime.baso = NULL: 

// go to the found text 

MCDoAction(myMC, mcActionGoToTime, kmyNewTime): 

// highlight the text 

TextNsdiaHIliteTextSamp| e (myHandler, rnyFoundTime, 

gOffset, gOffset + theText[0] » kmyColor): 


I else [ 

QTFr ame_Beep () ; // if the desired string wasn't found, l>crp 

i 

i 

//end if 

// update rhe current offset, if wore searching forward 

If (gSearchForward (myErr = noErr)) 
gOffset +- theText [0]; 


Of course, your code won’t need to use this compiler flag; 
you'll call just MovieSearchText or TextMediaFindNextText for 
your text searching. 1 fere we simply want to illustrate how Lo 
call both of these functions. 


void QTText_F1ndText 


App 1 i cat 1 oriDataHd 1 
Movie 

KediaHandier 
KovieCom roller 
long 

TimeValue 

OSErr 


(WindowObject theWindowObject* 

Str255 theText) 


myAppData = NULL: 
myMovie - NULL; 
myliandler = NULL: 
myMC - NULL: 
my Flags = 01.: 
myTimeValue; 
myErr = noErr; 


myAppData “ (Appli rati onDistaHdl) 

QTFratne._GetAppr>ataFromWindowQb ject (theWindowOhJect) : 
if (myAppData — NOLL) 
return; 


myMC = (**theWindowObJect).fController: 
myMovie - (* *theWirid owObj set). fMovi©; 
myHandler = (* *myAppData). fTextHandler: 

// set the search features 
myFlags = findTextlJseOf f set; 
if (I gSearehFonward) 

myFlags [— findTextReverseS.earth: 
if (gSearchWrap) 

myFlags |= findTextWrapAround: 
if (gSearchWlthCase) 

myFlags |= findTextCaseSensitive: 

myTimeValue = GetMovieTime(myMovie. NULL); 

#1£ USEJMGVIE5EARCHTEXT 

myFlags — searchTextEnabledTraoksOnly; 

myErr = MovieSearchText{myMovie, (Ptr)(^theText[1]), 

theText[0]. myFlags, NULL, &myTimeValue. frgOFfset); 
if (myErr != noErr) 

QTF ra me_B eepO : // if the desired stri ng wasn i found, beep 

//else 


Text Editing 

Let s consider now how to edit the data in a text 
track. Conceptually, this is a fairly simple operation. We 
can just call DeleteTrackSegment to delete one or more 
existing text samples from a track; then we can call 
TextMediaAddTextSample to add a new text sample to the 
text media and then InsertMedialntoTrack to place that text 
sample at the desired location in the track. For the 
moment, well limit ourselves to replacing a single 
existing text sample by another sample that occupies the 
same location in the track (that is, that has the same 
starting point and duration as the original sample). 

When the user selects the “Edit Current Text..,” menu 
item, well display the dialog box shown in Figure 12. If 
the user clicks the OK button, well retrieve the text from 
the edit text control in that dialog box and use that text 
as the replacement text data. There are only two things 
we still need to figure out: (I) how can we get the text of 
the current text sample (to put into the dialog box when 
ids first displayed)? And, (2) how can we determine the 
starting time and duration of the current text sample? Let s 
take these tasks in order. 
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Sample 

Enter the tent of the current sample: 
We forgot to seed! 


[ Cancel ] 

Figure 12: The Edit Text dialog box , 


OK | 


Getting the Current Text 

The firs! task is the easier of the two, mainly because 
whenever the text media handler is about to display a 
new text sample, it calls an application-defined text 
callback procedure that we he previously installed by 
calling TextMediaSetTextProc (in Listing 6 ). The text 
callback procedure is passed several parameters, one of 
which is a handle to the sample data of the current media 
sample. So all we need to do is make a copy of the 
sample text in a place we can find it when we are about 
to display the dialog box shown in Figure 12. Listing H 
shows our application's text callback procedure. 


Listing 8: Getting the current text 


QTTcxt TcxtPnx 


PASCAL_RTN QSErr QTTexv.Text. Free (Handle theText, 

Movie theMovie, short *theDisplayFlag, long theRefCon) 
I 

pragma unused (rheMovie, theRefCon) 
char *myTextPtr = NULL; 

short my Text Size; 

short my Index: 

// on entry to tills function, thcText is a handle to the text sample data, 

// which is a big-endian 16-bit length word followed by the text itself 

myTextSise = EndiantJ16JBtoN(*(short *)(*theText)): 
myTextFtr - (char *)(*tbeText + siseof(short)); 


to be shown or not shown, regardless of the media's 
default display flags.) 


Finding Sample Boundaries 

Now we need to figure out how to find tire starting time 
and duration of the current text media sample (so we know 
what segment of the text track to replace). An easy way to 
get the starting time would be to call GetMovieTime in our 
text callback procedure and then assign the returned value to 
a global variable. A better way — because it can be used 
with media types other than text — is to call the 
GetTrackNextlnterestingTime function inside the 
QTText_EditText function, GetTrackNextlnterestingTime allows 
us to search for specific times in a track, given a set of search 
criteria. The search criteria are specified by these flags: 


enum I 

nextTimeMediaSample 

nextTimeMediaEdit 

nextTimeTrackEdit 

nextTimeSyncSample 

nextTimeStep 

nextTimeEdgeQK 

nextTimeI gno reActiveSegment 


- 1 << 0 . 
- 1 « 1 . 
= I << 2. 
1 « 3 , 

1 << 4 t 
I << 14, 

“ 1 « 15 


For present purposes, we’ll use the two flags 
nextTimeMediaSampEe and nextTimeEdgeOK, which tell 
GetTrackNextlnterestingTime to search in the next sample 
in the track’s media hut to consider samples that begin or 
end at the search starting time. 

Well begin by getting the current movie time (which 
might not be the beginning of the current text sample), 
like this: 

rnyMovieTime - GetMovi e*T i me (myMovIe * NULL): 

Then we want to search backward to find the beginning 
of the current media sample: 


// ropy the text into our global variable 

for (myIndex “ 1; mylndex <= myTextSize; 

myInde>H-+ 1 myTextPtrH) 
gSampleText [mylradexj = *myTextPtr: 

gSampieText [C 1 ] = myTextSize; 

// ask tor the default text display' 

*theDisplayFlag = txtProcDefaultDisplay: 

return(noErr); 

1 

As you can see, we first parse the sample data to get 
the 16 -bit length field and the location of the first 
character in tiie text string. Then we copy the characters 
into the global variable gSampleText, which is of type 
Str255. Finally, we return the value txtProcDefauttDisplay in 
the parameter the Display Rag; this instructs die text media 
handler to use the display flags contained in the 
displayFlags field of the text description structure for that 
text sample, (There are also constants to force the sample 


SetTrsckNe'KtlnterestingTimef 

myTrack, 

next Time Ed geOK | n ext TimeMedi a Sample. 
myMovieTlme, 

• fixed1, 

tmylnterestingTime. 

NULL); 

The third parameter specifies the starting time for the 
search and the fourth parameter indicates the direction of 
the search; because the value here is negative, the search 
goes backwards from the current movie time. Once 
GetTrackNextlnterestingTime finds the beginning of the 
current media sample, it returns that time in the location 
pointed to by the fifth parameter. We Ve set the sixth 
parameter to NULL because we don't need the duration 
from the current time to the found interesting time to be 
returned to us. 

So we've found the beginning of the current text 
sample. We can find the duration of that sample by calling 
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GetTrackNextlnterestingTime once more, this time searching Toolbox currently provides Lliree constants for track 

forward from the beginning of the sample, like this: reference types: 


myMovi&Time = mylnterestingTime: 

GetTrackNextlnterestingTime ( 

myTrack. 

nextTimeEdgeQK | nextTinteMediaSample, 
myMovieTime * 
fixedI, 

NULL,. 

&myDuration) : 

In this case, we want only the duration of the sample 
returned to us, so we pass NULL in the fifth parameter and 
&myDuration in the sixth. 

Keep in mind that the time values that 
GetTrackNextlnterestingTime returns to us are in the movie 
time scale. This Is useful, since the parameters to 
DeleteTrackSegment must also be in the movie time scale. 
So we can now call DeleteTrackSegment to remove the 
current text sample from the track: 

myErr = DeleteTtuckSegment(myTrack. mylnterestingTime. 

myEuration): 

All that remains is to add a new text sample in place 
of the one we just removed For this, we can call 
TextMediaAddTextSample as we did earlier. There is only 
one complication here: the duration we pass to 
TextMediaAddTextSample must be expressed in the media 
time scale, not the movie rime scale. Bui the Movie 
Toolbox conveniently provides the 

MediaTimeToSampleNum function that we can use to get 
the start time and duration of the current media sample in 
the media lime scale, like this: 


etsum I 

kT r ackRefe renc eChapte rLi s t = FQUR_CHAR_CQDE {’ chap ’), 

kT r ackRef e r enceTimeCod e = FOUR_CHAR_CODE (* tmc d *) , 

kT r ackRef e renc eModi f ier = EOURJCHARJBDE(*ssrc') 

1; 

A track reference of type kTrackReferenceChapterList is 
used to create a chapter track. A track reference of type 
kTrackReferenceTimeCode is used to create a timecode 
track , in which timecode values are associated with the 
samples of the target track. (Well consider timecode 
tracks in more detail in the next QuickTime Toolkit 
article.) A track reference of type kTrackReferenceModifier 
is used to create a modifier track; modifier tracks are 
useful when you want one track to modify the 
appearance or behavior of a target track. For instance, a 
tween track is a kind of modifier track that can be used 
to change, say, the volume of a sound track as the movie 
progresses. Well encounter modifier tracks in several 
upcoming articles, to change the current image of a sprite 
track and to apply a special effect to a video track. Other 
parts of QuickTime define additional types of track 
references. For example, the file QuickTimeVRFormat.h 
defines several types of track references that are used in 
building QuickTime VR movie files. 

Ids actually a rather trivial operation to create a 
chapter track once we have a text track at hand. If 
myTypeTrack is a track identifier for a target track (in the 
present case, a video track), then we can create a chapter 
Lrack reference to our text track like this: 


myMovieTime = GetNoviGTiEn&fmyNovie, NULL); 
myMediaCurrentTime = TrackTiinGToMediaTime 

f myMovieTime. 


Med1aTimeToSamp1eNum( 

myMedia r 

inyMediaCurrentTime. 
&myMedi aSamp I e I nd ex. 
&rnyMe d 1 aSamp le S t a r t Time, 
SimyMed iaSarapleDuration); 


EiyTrack); 


So, we've got all the information we need to call 
TextMediaAddTextSample and InsertMedialntoTrack and 
thereby complete the text sample editing operation. For the 
complete definition of GTText_EditText. see the file GTText.c. 

Chapter Tracks 

We learned earlier that a chapter track is just a text 
track that has been associated in a particular way with 
some other track. Let's call this other track the target 
track We create the association between a text track and 
the target track by creating a track reference from that 
target to the text track. In general, a track reference is 
simply a way for one track to establish a relationship with 
some other track. The type of the track reference 
indicates the nature of that relationship. The Movie 


AddTrackRef^rence(myTypeTrack, myTextTrack, 

kTrackRef erenceChapterList , NULL): 

The Iasi parameter is a pointer to a long word in which 
AddTrackReference will return the index assigned to the 
new track reference; we don’t need this information, so 
we set that parameter to NULL 

All Lhe chapter titles must be contained in a single 
text track; we specify the starting time for chapters w r hen 
we add the text to the text track by calling 
TextMediaAddTextSample. Note that we need to create the 
chapter association only between the text track and one 
other target track, not between the text track and all other 
tracks in the movie. The target track must be enabled, but 
typically the chapter track is not enabled (unless we want 
Lhe text track Lo be visible). 

It’s also very easy to remove a track reference and 
hence to change a chapter track back into a non-chapter 
text track. Again, if myTypeTrack is the target track, then 
we can disassociate it from the text Lrack by calling 
DeleteTrackReference, like this: 

DeleteTrackReference(myTypeTrack, 

kTrackReferenceChapterList» 1 ): 
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Here the last parameter is the index of die track reference 
of the specified type that we want to remove. Our code 
attaches at most one chapter track to a target, so we can 
safely set that index to 1. 

Listing 9 shows our complete function for turning a 
text track into a chapter track or turning a chapter track 
back into a text track. The Boolean parameter 
isChapterTrack determines whether the first text track in 
the movie becomes a chapter track or is demoted from 
that lofty rank. 


Listing 9= Setting and unsetting chapter tracks 

QTTvatJS ct' FexJTiackAst Luip teiTrack 


OSErr QTText etTextTrackAsChapter-Trad* 

[WindowObject theWindowObject. OSType theType, 

Boolean isChapterTrack) 


App1ic a tionDataHd1 
Movie 

MovieController 

Track 

Track 

OSErr 


myAppDsta = NULL: 
myMovie = NULL: 
myMC - NULL; 
myTypeTrack * NULL: 
myTextTrack = NULL: 
myErr = paramErr: 


// get the movie, controller and related stuff 

myAppData = [ApplicatianDataHdl) 

QTFrameJ^tAppDataEromWindowQbjeet EtheWindowOhject ); 
if (myAppData = NULL) 
return(myErr): 

myMovie = (**xheWindowQbjeer). fMovie; 
myMC = (**theWindowQbjeci).fController; 
myTextTrack = {* ^myAppData).fTextTrack; 

if [ (my Mo vie != NULL) (myMC I- NULL)) f 

myTypeTrack - GetiflovielndTrackType(myMovie, 1, tbeType, 
movieTrackMediaType | movieTrackEnabladOnly); 
if ((myTypeTrack ] = NULL) G.& (myTextTrack != NULL)) ! 

// add or delete a track reference, sis determined by the desired final stale 
if [isChapterTrack) 

myErr = AddTrackReferenee(myTypeTrack, myTextTrack, 
kTrackReferenceChapterList, NULL): 

else 

myErr = DeleteTrackReference (myTypeTrack, 

kTrackReferenceChapterList* 1): 

// tdl die movie controller we’ve changed aspects of the movie 

MCMovieChangedfmyMC, myMovie) : 


// stamp the movie as dirty 

(**theWindowObject).flsDirty — true: 


return(myErr); 

} 


Note that after we call AddTrackReference or 
DeleteTrackReference, we need to call MCMovieChanged to 
inform the movie controller that we've changed the 
associated movie. This prompts the movie controller to 
redraw the movie controller bar to show or hide the 
chapter pop-up menu. 

The file GTTexLc contains a number of other chapter 
track utilities, listing 10 defines the one we use for 
determining whether a track is a chapter track; we call this 


function when we need to determine whether to place a 
check mark next to the ''Chapter Track’’ menu item. 

Listing 10: Determining whether a track is a 
chapter track 


QTTextJsC LiaptcrTrack 

Boolean QTText^IsCbapterTrack [Track theTrack) 

[ 

Movie myMovie * NULL; 

Track myTrack = NULL: 

long myTrackCount = QL; 

long myTrRef Count = QL: 

long myTracklndex: 

long rayT rRe fInd ex: 

rayMovie = GetTrackMovie{theTrack): 
if (myMovie = NULL) 
return (false); 

myTrackCount = GotMovieTrackCount[myMovie): 

for (myTracklndex = 1; myTracklndex <* myTrackCount; 

myTracklndexhf) l 

myTrack = GetMovielndTraek(myMovie, myTracklndex): 
if [(myTrack 1= NULL) && [myTrack 1= theTrack)) l 

// iterate thru all track references of type kTraekRderenceChaprerlist 

myTrRefCount = GetTrackReferenceCount [myTrack* 

kT ra ckReferenceChapte rLis t): 
for (myTrRefIndex “ i; myTrRefIndex <= myTrRefCount: 

myTrRefIndex++) ! 

Track myRefTrack = NULL: 

myRefTrack 3 GetTrackReference(myTrack* 

kT rac kRef e r e n c eChapt.e rLi st * myT rRef Index): 
if (myRefTrack = theTrack) 
return (true); 

] 

1 


return(false); 

I 


Hypertext Reference Tracks 

A hypertext reference track, or HREF track, is a text 
track in which some or all of the samples contain 
hypertext links, in the form of URLs. (Actually, there’s no 
requirement that any of the samples in an HREF track 
contain a hypertext link, but then of course it's not very 
useful,) These URLs can be any kind of URL supported by 
QuickTime* including HTTP* HTTPS, FTP, file, RTSP, and 
JavaScript URLs. Indeed, if the QuickTime Plug-In finds a 
URL it doesn’t recognize, it passes it to the web browser 
for processing. So, really* the sky’s the limit in terms of 
the kind of URLs we can put in an HREF track* 

From a programming perspective, creating an HREF 
track is even easier than creating a chapter track* All w r e 
need to do is set the name of a text track to “HREFTrack”. 
The plug-in interprets the first text track in a movie 
having that name as the active IIRFF track. Listing 11 
defines the function QTText_SetTextTrackAsHREFTrack that 
we can use to set and unset a text track as an HREF track. 
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Listing 11: Setting and unsetting HREF tracks 

QTfcx t_SeiTextTrac kAsH R EFTrack 


QSErr (afTText_SetTextTr ackAsHREFTrack 

(Track theTrack. 


Boolean IsHREFTrack) 



OSErr myErr = noErr; 


myErr => GTUtils_SetTrackName(theTrack. 

isHREFTrack 7 kHREFTrackName : kNonHREFTrackNaine): 

return(myErr); 
t 

A track’s name is stored as pan of the track's user 
data, so QTUtEls_SetTrackName (defined in QTUtilitiesx) 
calls SetUserDataltem to set the name. In 
QTText_SetTextTrackAsHREFTrack, we use these constants 
for the track names; 


tap tte prat* tfAppltSuipt 
with Main imuftStviptivI 

For professionals and novices 
Webmasters and solution providers 


fdefine kHREFTrackName "KREFTrack" 

^define kNonHREFTrackName "Text Track" 

Ideally, each track should have a unique name (though this 
is not required)* So instead of hard-coding the name for the 
norvHREF track, we can generate a track name dynamically, 
looking at the names that are already assigned to tracks in 
the movie. QTUtilities.c defines a function, 
GTUtilsJWakeTrackNameByType, that we can call to 
accomplish this. Reworking QTText^SetTextTrackAsHR EFTrack 
to use QTUtils_MakeTrackNameByType is left as an exercise for 
the reader. 

Occasionally it's useful to know whether a specified 
text track is an HREF track. (For instance, QTText needs 
to know this to decide whether to put a check mark 
beside the "HREF Track” menu item.) The function 
QTText JsHREFTrack, defined in Listing 12, returns a 
Boolean value that indicates whether a given text track is 
an HREF track. 

Listing 12: Determining whether a track is an HREF 
track 

QTTextJsHREFTrdCk 

Boolean QTText_IsHREFTrack (Track theTrack) 
t 

Boolean IsHREFTrack = false; 

char ‘jnyTrackName — NULL; 

ntyTrackName - QTUt 11 SjGetTrackName(theTrack): 

If (rayTrackName 1* NULL) 

isHREFTrack - (strcmp(myTrackName. kHREFTrackName) =0); 
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freetmyTrackName) ; 
return (isHREFTrack); 


Some Loose Ends 

Let’s finish up by taking care of a few loose ends 
in our basic application framework that become 
apparent when we start working with text tracks. As 
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you know, when we paste some data Into a movie, the 
current movie time is set to the time immediately 
following the pasted data, (This is the standard 
behavior with any kind of pasting.) If pasting causes 
the movie box to expand, it might happen that the 
expanded portion of the movie box in the current 
frame contains areas that should be erased but which 
are not erased by the movie controller. For example, If 
we've added some text in parallel, we might see 
something like Figure 13. Here, the video media 
handler has redrawn the video portion of the movie 
box hut the text media handier, thinking (correctly) 
that there's no text for the current movie time, has left 
the text portion of the movie box untouched. As a 
result, the image of the movie controller bar, which 
used to occupy the space now occupied by the text 
track, is not erased. This is not good, but it’s easy 
enough to fix. 


□ m untitled.mou 0 



<|) gg 


Figure 13: A movie window after adding in parallel* 

When some part of the movie box needs to be 
redrawn, an update event is generated for that portion 
of the movie box. When we pass that event to 
MClsPlayerEvent, the movie controller redraws the 
appropriate portion of the movie and clears that area 
from the update region of the window. The problem, 
as we've just seen, is that the movie controller doesn't 
think that the bottom portion needs to be redrawn and 
hence doesn’t redraw it. We can solve this problem by 
erasing that portion of the window ourselves. Listing 
13 shows our updated version of QTApp_Draw. 


Listing 13= Redrawing a movie window 


QTApp_Dfaw 

void QTApp_Draw (WindowReference the Window) 

t 

GrafPtr mySavedPort * NULL: 

GrafPtr myWindowPort = NULL: 

Window? tr my Window = NULL: 

Rect myRect: 

GetPort (ScmySavedPort) ; 
myWindowPort = 

QTF ramejSe tPort Fr omWi nd owRef erenr efthe Window): 
royWirtdow = QfTFrame_GetWindowFromWindowReference(TlieWindow): 

if (myWindowPort = NULL) 
return: 

MacSetPort (myWindowPort) : 

ft if TARGET_AF 1_MAC_C ARBON 
^ GetPortBounds tmyWindowFort, &myRect); 

myRect = myWindowPort->portRect; 
ftend if 

BeginUpdate(myWindow): 

if (QTFrame_IsDocWindowCtheWindow)) 

EraseRect (fifluyRect) ; 

// “insert application-spec!Ik drawing here*** 

End Update (myWindow) ; 

MacSetPort(mySavedPort) : 

As you can see, we call EraseRect on the entire 
window rectangle. Keep in mind, however, that 
BeginUpdate limits the redrawn portion to the 
intersection of the visible region of the window and the 
current update region. Since MClsPlayerEvent will 
already have removed the active movie region from the 
update region, our call to EraseRect just redraws the 
visible portion of the update region that wasn't redrawn 
by the movie controller. 

The last thing we need to do is make sure that the 
entire movie box is included in the update region 
when we call MClsPlayerEvent. We can accomplish this 
by adding a few lines to our 
QTFrame_HandleEditMenuitem function. Essentially, we 
need to make sure to invalidate the entire movie box 
whenever the size of the movie box might have 
changed. Listing 14 shows the lines well add to the 
end of GTFrame_Handl 0 EditMenultem. 

Listing 14: Invalidating a movie window 


QTFrame _I iaridleEUitMeniil lem 

if if die si zt of the movie miglii have changed, Invalidate die entire movie 
box 

if ((theMenuItem = IDM_EDITUNDO) || 

{tfreMernilt eni = TOMBED ITCUT) | | 

(theMenuItem = IDM_EBITPASTE) ' | I 
(tfreMenuXtem = IDM_EDITGLEAR)) \ 

Rec t myRect: 

ftif TARGET_OS_WIN32 
RECT myWinRect: 

#endif 


90 


Word is Out 


MacTixh * November 2000 





















MCGetControllerBoundsRect {myMC, foittyRect): 

#if TARGET_OS_MAC 

Inval WindowRe c t (GTF rame_Ge t Wi nd owF romWi nd owR.e f e r enc e 

(tbeWindou)„ tonyRect); 

fendif 

ttif TARGET_0S_WIH32 

QTFranie_Coriver tMacToWinRect (&myRect. &myWirrRect); 
LnvalidateRect(theWindow\ fidnyWinSgct, False); 

#endif 

] 
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With these changes made, we should see no glitches 
like those in Figure 13 

Conclusion 

We've covered a fair amount of ground in this 
article. We've seen how to create text tracks, chapter 
tracks, and HREF tracks; we’ve also learned how to 
search a text track and edit the data in a text track. 
Along the way, we’ve seen how to upgrade our Edit 
menu item adjusting and our movie window 
redrawing, so that even our applications that are not 
directly concerned with text can import text from files 
or from the system scrap. 

We've also learned a more general lesson: 
QuickTime often provides more than one way to 
accomplish some particular task. We’ve seen, for 
instance, that we can call either AddMediaSample or 
TextMediaAddTextSample to add media samples to a text 
track. And, we can call either TextMediaFindNextText or 
MovieSearchTsxt to search for text within a text track. 
Which of these functions we use in any particular case is 
a matter of taste, no doubt, but also a matter of simplicity 
and code size. TextMndiaAddTextSample and 
MovieSearchText hold the dear advantage when we 
consider the amount of source code we need to write 
and the kinds of details ( like endian issues) that we need 
to attend to. In the future, we’ll generally opt for the 
simpler, cleaner way of solving our programming tasks 
(and leave the dinosaur bones for the archeologists). 
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by Jeff elites <onli ne@mactech. com > 


A few months ago we covered Quartz, Mac OS X’s new 2D 
graphics technology based on the imaging model of Adobe’s PDF. 
Quartz will lie responsible, directly or indirectly, for most of what die 
user sees on the screen. What we didn't emphasize direedy is that Quartz 
Ls 2D-only. Under Mac OS X, 3D graphics will lie I.rased on OpenGL So 
what's OpenGL? 

OpenGL is in, QiickDraw 3D ts out 

OpenGL is a 3D graphics library developed by SGI (then called 
Silicon Graphics). It’s a liigh-performance, crass-pkitform library, 
available on Mac OS 9, Mac OS X, Windows, and many Unix variants, 
and many video cards provide hardware acceleration. Ii is die library of 
choice for sophisticated 3D development, most notably the gaming 
industry. In particular, OpenGL is the basis if id software’s Quake games, 
and according to die company allows diem to develop their products 
with only a tiny amount of platform-specific code. This is important for 
the Macintosh community, because it makes it that much more likely that 
games and other 3D-graphics-intensive software (such as scientific data 
visualization, GAD, and architectural design packages) will lx_ j available. 

If you’ve done any 3D programming on die Macintosh in the past, 
you probably used QuickDraw 3D, the 3D library on Mac OS 9 and, 
technically, pan of QuickTime (and therefore available on Windows as 
well). The sad news is that OpenGL is replacing QuickDraw 3D on Mac 
OS X, not just providing an alternative. The worst part Ls that, while 
OpenGL Ls die industry standard. QD-JD is much easier to use for simple 
3D graphics. In fact, you could make the argument that OpenGL has a 
prohibitive learning curve for anyone wanting to do something simple— 
for instance, creating a 3D bar graph, ft has a large procedural API, and 
it’s yet another conceptual barrier you have to cross to gel your 
application written. It also lacks QD-3D*$ elegant object-oriented (though 
still C-based) API, and well as its file format for storing 3D objects, On 
the other hand, you could make a strong counterargument that “simple” 
uses of 3D graphics are few and far lie tween, and somewhat of an 
oxymoron—when’s die last time you saw 3D graphics outside of a 
game, a semen Silver, or a splash screen? In this light, there are certainly 
more people cheering the availability of OpenGL than are mourning the 
loss of QD-3D, but it would have been nice to retain an easy-to-use, 
high-level API, possibly layered on top of OpenGL. Although they seem 
to fit well together, there’s no indication dial Apple will go this route, and 
if diere really are very few developers using QD-31X it makes sense not 
to devote die resources to it. 

Enter Quesa 

Now die good news. The good news is Quesa, a third-party’, open- 
source (LGPL) effort to recreate QI>3D from scratch—in other words, 
and independent library which is API-compatible with QD-3D. This 
approach is really a win-win situation for the Macintosh community, 
because it frees Apple from the burden of maintaining an API which may 
not lie widely used, yet it will still lie available to diose who need it, for 
as long as anyone is interested enough in it to maintain it. The needs- 
based focus of many open-source projects is dearly present in Quesa, 


which was started because its founder wanted to lie able to run his 3D 
screen saver on Mac OS X. The project is under active development, and 
in fact is mostly complete at this point. As a side benefit of die open- 
source approach, it Ls now truly cross-platform, available now on Mac OS 
9, Mac OS X, Windows, and Linux, and coming to the BeOS as well. And 
as you might expect, Quesa can run on top of OpenGL, and so it will 
lienefit from OpenGL hardware acceleration. As mentioned above, QD- 
3D (and hence Quesa) Ls object-oriented aldiough w ritten in C This is 
interesting from a design standpoint, and Ls similar in spirit to Apple's 
new CoreFoundation API. which gives C-based access to key data types 
and APIs which originated in Cocoa. You can read more about Quesa’s 
structure on its documentation page. 

Quesa 

<http://quesa.org/> 

Quesa - Documentation 
<http://quesa.org/reference/docs.htnnl> 

Quesa Resources 

If you are moving into 3D graphics, there are several places you 
can start in order to get up Lo speed. If you are interested in the QD- 
3D/Quesa approach, you'll get a good overview from a series of articles 
which originally appeared in Apple’s develop magazine, and you’ll also 
want to become familiar with Apple's QD-3D documentation, which is 
available through the QuickTime section of their developer web site. 
Next, of course, you should take a look at Quesa itself, and download 
the libraries or source code. There is an active Quesa mailing list, which 
you’ll want to subscribe to, as Quesa is still evolving and there are sure 
ro be discussions of current problems and future directions. You might 
also want an overv iew of how QD-3D and OpenGL compare, so diat 
you can make an informed choice about which approach you want to 
take. You can start by checking out an article “Must-See 3-D Engines” 
from BATE Magazine, which compares OpenGL, QD-3D, and 
DirecQD, and then take a look at the information and resources in a 
past MacTech Online column from March 1998, written by my 
predecessor. Both of these are somewhat old and may no longer be 
accurate in their details, but they’ll give you a feel for how die APIs 
differ in their approaches as well as their consequent strengdis and 
weaknesses. Also, there is an FAQ, ns well as several link lists which 
you can consult to find further information. 

QuickDraw 3D: A New Dimension for Macintosh Graphics (June 1995} 

<http://www. mactechxom/a rtkIes/develop/issue_2 2/qu ickdra w. htrri I > 

The Basics of QuickDraw 3D Geometries (September 1995) 

< http://www. mactech xom/a rtides/de velop/(ssue_23/thom psonfe rn icol a. html> 

New QuickDraw 3D Geometries (December 1996} 
<http://www.mactech.com/artides/develop/issueJ8/schneider.html> 

QuickTime API —QD3D 

<http://developer.apple.com/techpubs/quicktjme/qtdevdoG/RM/qd3dframe,htm> 

Quesa - Mailing List 

<http://quesa.org/info/list.htm!> 
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Must-See 3-D Engines 

<http://wwvw-hyte.a3m/art/9606/sec11/art-4.htm> 

March 1998 Maclech Online 

<http://www.mactech.com/articles/mactech/Vol. 14/14.03/Mar98MacTechOnline/> 
QuickDraw 3D FAQ 

<http://www.amplifSedintelligence.com/QD3DFaqContents.html> 

Stefan Huber's QD3D Links 
<http://www.topoi.ch/3d.htmb 
Quesa - Links 

<http://que5a. org/oth er/l inks.htm I > 

QuickDraw 3D Resources 
<http://www,desig ncommun i ty.com/qd3d. htm I > 

OpenGL Resources 

OpenGL itself is an open standard, and the hub of information 
about this library is at the OpenGL home page, Here you'll find an 
overview for developers, links to tutorials, and information about the 
large assortment of books available on OpenGL (including the reference 
standards The OpenGL Programming Guide: The Official Guide to 
Learning OpenGL and OpenGL Reference Manual ). As I mentioned 
above, OpenGL has a large API with a significant learning curve, but it 
is probably worth die effort if you plan to do hard-core 3D. To make 
your job a little easier, read up on GLUT, die OpenGL Utility Toolkit. It's 
a simplified, window-based API which is geared toward those learning 
OpenGL nr using it to writer smaller programs, (GLUT does ship with 
Apple's OpenGL implementation, by the way.) You can find links to 
additional resources at the site of the Mesa project, which is an 
independent library with an OpenGL-compatible Aid. If you just want 
to get a flavor for the OpenGL API, try out a recent article on the O’Reilly 
Network which describes how to use OpenGL to simulate a black hole 
freally), and also links to additional introductory articles, Finally, keep an 
eye on Apple’s sample code pages for examples of using OpenGL from 
Cocoa and Carbon, and download die SDK to gel you started. 

OpenGL Home Page 
<http://www.ope ngl. org/> 

Overview of OpenGL 

<http://www.opengl.org/developers/about/overview.html> 

OpenGL Tutorials and Courses 
<http://www.opengLorg/developers/code/tutorialshtml> 

Books on OpenGL 

<http://www.opengl.org/dlevelopers/documentation/books.htnil> 

GLUT - OpenGL Utility Toolkit 

<http://www.opengl.org/developers/doajmentation/glut.htmj> 

Mesa - Links 

<http://www.mesa3d.org/linkshtml> 

Building a Black Hole With OpenGL 
<http://www.oreiilynet.eom/pub/a/380> 

Apple Sample Code - Graphics 3D 

<http://developer.apple.com/samplecode/Sample_Code/Graphics_3Dhtm> 

Apple's OpenGL SDK 

<http: //developers pple. com/opengl/index. html> 

3D Graphics Foundations 

Before you dive into a particular ALL you may want to get a feel 
for the field of 3D graphics in general. If you’ve never worked with it 


before, there's quite a bit of conceptual background you’ll need, and if 
you plan to work with it extensively there is also quite a bit of math. The 
classic text is Computer Graphics : Principles And Practice by Foley, 
Feiner, and Van Dam (ISBN 0201848406), and it is thorough and dense, 
covering both 2D and 3D graphics. For some lighter reading try the two 
book’s by Jim Biinn, Jim Blinns Corner: A Trip) Down the Graphics 
Pipeline (ISBN- 1558603875) and Jim Blinns Corner: Dirty Pixels (ISBN; 
1558604553). They’re not a full curriculum but they will give you a feel 
for some of die interesting and often intricate parts of the field. 

3D and Cocoa 

Another “interesting” facet of the move to OpenGL for Mac OS X is 
that we seem to lie without a Cocoa-based API for 3D graphics. 
Certainly, you can use OpenGL from within Cocoa applications— 
Objective-C was designed to lie an extension to ANSI C, so there is no 
technological barrier to using a C-based API from within a Cocoa 
application, but it would be more convenient to have a fully object- 
oriented API to work with, and developers are likely to create their own 
object-based wrappers for the parts of the API they arc using, it would 
be nice for someone to do diis once and for all, and develop a higher- 
level Cocoa-based library that everyone could use. There is some hope 
for such an animal as part of the MiscKit project. Hie MiscKit Ls a 
collection of Cocoa-based classes and utilities, assembled under an 
open-source model lx 1 fore “open source* became a household term 
There are all kinds of useful tidbits in the MiscKit, although they are still 
in the process of being updated for the current Cocoa libraries (as most 
of the Kit was developed for NeXTStep or OpenStep). Of immediate 
relevance ls something called the 3D Kit. which was originally developed 
by NeXT and later transferred to the MiscKit main tained (it remains a 
logically separate project). There appear to lx a few licensing issues 
which may need to lx* worked out, but with a little luck this could serve 
as a strong starting point for a high-level 3D framework for Cocoa, or at 
least as an API model for such a framework. 

The MiscKit Frameworks 
<http://misckit.org/> 

Moving Forward 

With OpenGL as a first-class citizen on the Macintosh platform, 
developers have a real choice of solutions for 3D graphics. It isn’t a direct 
result of the open-sourcing of the core of Mac OS X as Darwin, but 
open-source projects are becoming more and more relevant (and more 
an more important) to the platform, and are signaling a cultural shift in 
the Macintosh community as well as the programming community at 
large. The Macintosh platform is becoming less- and less proprietary, and 
Macintosh developed are becoming more aware of valuable resources 
which originated on other platforms, and of their own ability to tike part 
in the process of moving these technologies to the Macintosh, And 
although it’s easy to overlook at first, this is completely in line with the 
original motivation for the Macintosh, and for Apple as a company: 
bringing the power of technology to the individual, and letting him make 
Ills own choices. Now, more drain ever, this means giving this power and 
choice to the Individual developer, as well as to the end user. It’s our 
responsibility to take advantage of tills freedom, and participate in 
driving the platform forward. (ED 


94 


MacTech Online 


MacTecii • November 2000 







MacBuy.com, The Macworld PriceFinder, reviews and compares out-the-door 
prices of available Macintosh products from a wide array of online vendors. 
You'll quickly find the best product for your needs, and you'll also find the 
best price. Shop and compare computers, new and upgrade software, 
printers and more - it's all there. 

The Macworld PriceFinder is your comprehensive resource for choosing 
the best Macintosh products, getting the lowest prices and buying with 
confidence from the vendor of your choice. 

rrmcBLivcom 

The Macworld PriceFinder 
www.macbuy.com 

Mac Publishing. L.L.C. Macwmld.com arc trademarks of Mac PuhEishinfi Macintosh is a registered trademark of Apple Computer. Jnc. 


Compare the best Mac products 
at the best prices. 





Continued from page 4 


administrator attending his first Summit told me that 
the presentation on Web STAR Mail DNS Settings had 
been worth the price of the Summit in itself. Other 
presentations in this track were of a more general 
nature, dealing with XML and Perl and a detailed 
technical discussion of the Internet’s infrastructure. I 
attended an excellent introduction to XML by 
developer whose company publishes a server-side 
XML interpreter. Why wait for browser support? he 
asked. Why indeed? 

4D DOES THE WeBj too 

Almost a third of the presentations at the Summit 
dealt with the Web. On the 4D side of the Summit, 
there were several presentations devoted to the new 
web features in 4D 6.7 (forthcoming), especially the 
Web Assistant, the first of the 4D "components.” The 
Web Assistant makes it easier than ever to build Web 
sites using 4D alone. The keynote showed a demo of 
another component, a tool for building online stores, 
code-named “Yapee." (One rumor had it that this is the 
name of the French developer.) 4D 6.7 supports SSL. A 
set of extensions for Macromedia Dreamweaver are in 
development right now, to give 4D developers the 
ability to use Dreamweaver’s outstanding web page- 
design tools to build pages that will display data 
dynamically drawn from 4D databases. In our 
interview, Brendan Coveney told me that 4D, Inc. is 
deeply committed to the Web’s future, which lies with 
dynamic, database-driven web sites. 

Other presentations delved into topics like “4D as 
a WAP Server” and il e-Commerce with 4D.” The latter 
was presented by the maker of Web Server 4D (WS4D), 
a remarkable off-the-shelf web serving and e- 
commerce application which proves almost better than 
anything else how powerful and flexible 4D’s 
programming language is: WS4D—in many ways a 
competitor of 4D now —is itself programmed entirely 
in 4D! In the "beginner’s track," I presented a well- 
attended session on using 4D as a backend for Lasso- 
driven sites. Not in the beginner’s track, 4D maestro 
David Adams gave an advanced full-day seminar in 4D 
Web techniques after the main part of the Summit. 

4D 6*7 and OS X 

In the keynote, Brendan Coveney played a snazzy 
little game called Time Matrix, written in 4D by the 
folks at Data Craft. (DataCraft is the publisher of 
Foundation, a brilliantly designed shell widely used by 
4D developers.) Time Matrix was run first under OS 9, 
then it was run again, under OS X beta. In view of the 


obvious complexity of the underlying code, the 
remarkable thing was not that the second demo 
sported the Aqua look, but that not a single line of 
code had to be rewritten. 

The folks at 4D, Inc. are committed to (if not 
downright obsessed with) making sure that old systems 
don’t break when new ones are released. I was assured 
by several different developers on different occasions 
that it is possible to open a 19B7-vintage version 1.0 
database in the year 2000 under 4D version 6.5 and 
that it will in all likelihood run fine with few or no 
changes. After demonstrating that the core 4D 
application itself will make the transition to OS X 
without a hitch, Coveney went on to tell developers 
that 4D, Inc. is working very hard to make sure that it 
is as easy as possible for plug-in developers to port 
their products to OS X. 

AreaList Pro is dead* Long live PowerView! 

I am not an old-enough hand with 4D to know the 
story first-hand, but I have heard it many times from 
experienced developers. They sit down and get a far¬ 
away look when they start to tell you about it, the way 
veterans do before talking about The War. It goes 
something like this: There used to be a tinrd-party 
plug-in for 4D called AreaList Pro, which was relied 
upon by every serious 4D developer. AreaList provided 
a set of life-saving functions not built into 4D, all of 
them derived from its central trick of displaying arrays 
on screen. AreaList was a VBD (very big deal). 

Then one dark day, the company that had been 
publishing AreaList and several other crucial ID tools 
decided that its own business plan no longer included 
4D and that it would stop developing and supporting 
these tools. To hear the old-timers tell it, it was like 
waking up tomorrow to discover that you could not 
buy gasoline for your car—anywhere. 

At last year’s Summit in Chicago, 4D, Inc. promised 
developers that il would solve the problem caused by 
AreaList’s death, and this year, they delivered on the 
promise by announcing PowerView, a new tool in 6.7 
which combines the features of ALP and 4D Chart (4D\s 
spreadsheet plug-in). The demo of PowerView showed 
it to be fast and flexible. One part of the demo 
consisted of a ballet of formatted table cells that 
Brendan Coveney had to assure the audience had not 
been done in Flash! Several developers I talked to 
thought that, while the preview of 4D running under 
OS X was good news, the announcement of a 
replacement for AreaList Pro was the news that 
mattered most to them. 
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To me as a rookie 4D user still spending most of 
my time on the bench, it was interesting to discover 
that there are still companies brave enough to make 
promises and at least equally interesting to see a 
company actually keep them. 

Everything Else 

The rest of the program was nicely diversified. One 
presenter in the WebSTAR track warned his audience 
that his talk was going to get a bit geeky. He needn’t 
have bothered. The entire conference was 
unashamedly geeky. The level of discourse among the 
attendees was consistently high. Even the beginners 
track included presentations likely to make expert 
FileMaker users like me sweat a little, such as 
“Parameter Passing and Generic Code,” "Accelerated 
Text Parsing with BLOBs/’ "Pointers on Pointers,” and 
"Multi-Process Programming/’ Other presentations on 
4D were similarly diversified, dealing with memory 
management, interprocess data transfer, and 
localization of applications. [ was not able to attend 
the latter, but its presence on the program reminded 
me of 4D’s international character 4D, Inc, in the U,S. 
is a wholly-owned subsidiary whose parent country is 
in France. 4D has long provided extraordinary support 
for international users, including full-support for 
double-byte languages like Chinese and Japanese. 

A few of the sessions were bleeding edge, 1 
attended a session on using speech-recognition and 
synthesis as a replacement for the conventional UI. 
The session was fascinating, especially when the 
presenter’s demo behaved as expected. I left feeling 
that 1 might personally wait a year before worrying 
about this subject again. 

Because you have complete control over the UI 
(including menus) and because you can compile your 
code into double-clickable programs, 4D is a great tool 
for developing vertical market applications, A couple 
panel sessions provided detailed advice for commercial 
developers from those who have already been there 
and done that. I personally learned that we at 
Polytrope have been doing almost everything wrong, 

Windows? 

The casual observer could easily have gotten the 
impression that this was a convention attended 
exclusively by Macintosh users. C.K. Hahn, Senior 
Director, Developer Technical Services, Apple 
Computer, Inc,, spoke briefly during the keynote to 
give Apple’s blessing on 4D, Inc/s commitment to OS 
X, Apple sponsored the wonderful Internet cafe for 
Summit attendees, complete with an Airport base 
station. Many of the sessions dealt specifically with the 


Mac OS. My completely unscientific guess is that a 
good eighty percent or more of the attendees would 
consider themselves primarily Mac OS users. And yet 
4D is a cross-platform product. More than that: 
Brendan Coveney told me that roughly 75% of their 
sales are for the Windows platform (mainly 4D Server 
for NT boxes)! This paradox leads me to two 
observations. First, it appears that developing 4D 
databases on the Mac and deploying them under 
Window's is easy and reliable. If there w r ere a lot of 
problems in this arrangement, I would have expected 
to see at least a couple presentations like “Pot-holes to 
avoid with the Windows compiler” or “Memory 
Management under Windows NT/’ Second, the market 
— not just 4D, Inc/s market, but my market, the 
developers 1 market — is Windows. 

The Big News 

On the last day, I asked everybody I talked to what 
the big news of the Summit was. Some said it was the 
acquisition of WebSTAR by 4D, Inc. Some mentioned 
PowerView. Some pointed to the web features of the 
forthcoming 4D 6.7. Many talked with excitement 
about seeing 4D running under OS X. But w'hen I 
asked Brendan Coveney what the big news was, he did 
not hesitate to give me the low-tech answer that 1 think 
is the best of all: "The big news of the Summit is that 
the 4D community is alive and growing and the 
atmosphere is tremendously positive.” 

Credits and More Information 

Many thanks to those credited above and to many 
others not credited for speaking to me. Special thanks to 
John Steele of Elucidate in Fort Worth for his clarifications 
with regard to AreaList Pro. The official 4D Summit web 
site is at <http;//www.4DSummit,com>, but you need a 
password to get into the really useful pages. No password 
is required to get into developer and Summit presenter 
Bryan Green’s unofficial celebration of the Summit: 
<http://www.4DSumniitnotes.com>. Ei 
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AUTOMATION 


By Bruce Lawton 


Talking to Your Home 


Introduction 

The futuristic world of talking to 
your home to operate everything in it is 
here now! Well, how many times have 
we heard claims like that? The truth is; 
for some it really is here now; for 
others, it is not quite ready yet. Speech 
recognition technology is delivering 
some amazing results already and it is 
just getting better as the computers get 
faster and the recognition software 
continues to improve. 

To make it happen, we’ll be talking 
about voice commands, microphone! s), 
a Power Macintosh, software, X-10 
home automation hardware and your 
existing lamps, appliances and other 
gadgets. This discussion assumes 
you're already familiar with general X- 
10 home automation. If not, check out 
the June 2000 issue of MacTech, 

Why You Might Want to Use 
Voice Commands 

The most useful application for 
speech recognition is for persons 
wanting to overcome a physical 
handicap. With limited mobility or limited 
dexterity, speech recognition enables 
someone to operate lamps, appliances 
and home entertainment units that would 
otherwise Itc difficult or impossible to 
operate. In this way, the quality of life 
can be greatly improved, giving the 
person a bit more independence. 


For those who are not physically limited, operating 
the home by voice can lie a matter of convenience or just 
plain fun. How many times have you settled into bed and 
then realized (perhaps with a little helpful reminder from 
your dear significant other) that some lights were left on? 
The easiest thing to do is to say "Turn off all lights,” 

It is also impressive to show your PC friends what 
your Macintosh will do in response to your voice 
commands. There’s nothing quite like seeing everyday 
hardware operated by voice. 



Figure /. From voice to lamp. 


Setting up the Microphone(s) 

To get started, you must first plan how you’re going 
to get your voice to your Macintosh, There are a! least 
three ways to do it. The most inexpensive microphone 
configuration is the standard PlainTalk, corded 
microphone connected directly to your Mae. The obvious 
drawback is that the cord restricts the distance you can go 
from your Mac while issuing voice commands. In some 
situations, this may be adequate. 

The most cost-effective approach giving you more 
range is to use a wireless microphone that transmits your 
voice as your own personal FM radio station. Then you 
have a small FM radio connected to your Mac to feed the 
sound in. The range on the microphone should enable 
operation from anywhere in a normal-sized home. My 


Bruce Lawton is still an enthusiastic Macintosh developer who first got hooked over 15 years ago. He can be reached 
at bruce@alwaysthinking.com. 
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own experience is that the Pro.2 microphone from Lotus 
Productions f www.lotusproductions,com, (800) 211-3778 
) works well and costs around $45. A small $25 radio from 
Radio Shack will receive the FM signal and should be 
connected to either your A/V Mac’s RCA input jacks or 
directly to the PlainTalk mic jack using a standard 3,5 mm 
stereo plug as shown below. The PlainTalk jack is really 
a stereo line-level input. The extra length of the plug 
allows the Mac to supply power to the tip which is then 
used by circuitry in the PlainTalk mic. The normal 3*5 mm 
stereo plug doesn’t use that available power. The 
headphone jack of the radio provides an audio signal 
compatible with the PlainTalk mic input. Make sure you 
adjust the radio headset volume to get the dearest sound 
with no clipping. 



price, from $70 to $250 or more. One of the most 
recommended models is the Crown PZM-11, sold at 
[Automate and SmartHome. 



Figure L In-wall microphones with a mixer. 


The Software 

For our purposes, there are two categories of speech 
recognition software: dictation and discrete commands. 
IBM’s ViaVoice is an excellent way to get your speech 
dictation into the Macintosh, but the resulting stream of 
words is not “understood” by the ViaVoice software* That is, 
it doesn’t know what action you want taken in response to 
the words. Dictation software is intended as an alternate 
method of text input — it is not going to help you operate 
your X-10 system. This is where you want software that 


Figure 2 . FM microphone and radio . 

The deluxe approach is to use in-wall microphones 
and a mixer. This costs the most, but can give you 
completely hands-free voice control from any room. There 
is a fair amount of experience in the 
comp.home,automation newsgroup from those who have 
set this up on Windows. It can work well, though I must 
admit 1 haven't done this myself — my own home has far 
too much “noise”. Wired microphones can be great for a 
home with one or maybe two people living there, but may 
not work well with several people. The Mac's PlainTalk can 
get confused if it is listening to many voices at once. When 
using in-wall microphones f each mic has a cable that is run 
back to the mixer, which is presumably near the Mac. The 
audio output from the mixer is then connected to the Mac’s 
sound input. Similar to the FM radio configuration, you can 
feed the line-level signal either into your A/V Mac’s RCA 
input jacks or directly into the PlainTalk mic jack using a 
standard 3-5 mm stereo plug. 

Shure (WWW.shure.com, (847) 866-2200) makes the SCM- 
410 and SCM-81G mixers with 4 and 8 inputs respectively. 
They dynamically cut out the microphones that are not being 
used, improving the audio quality for the microphone you’re 
speaking to. They cost $800 and $1,200 at [Automate ( 
www, iAutomate.com, (800) 741-6790 ). Home Voice also 
makes a mixer, sold as part of their “Multiroom Processor Kit” 
at SmartHome (www.smarthomexom, (800) 762-7846) for 
$690. Good, compatible, in-wall microphones vary greatly in 
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understands discrete commands. PlainTalk is at the heart of 
this type of speech recognition. As it has steadily improved 
over the years and CPU’s have sped up, Lhe reliability has 
become quite good. The Thinking Home application uses 
PlainTalk to make your XHO devices available. First, install 
PlainTalk. This is done via a “Custom' 1 installation from your 
MacOS CD or it can be downloaded from Apple's web site 
at <http://www.apple.com/macos/speeth/>. Next, ensure you 
have checked the “Respond to Voice Commands” checkbox 
in the Preferences as seen in Figure 4 



Figure 4 . Enabling speech commands* 

You need to have a device named "Bedroom Lamp” like 
the example of Figure 5 Now you can say “Turn off die 
bedroom lamp/' and Thinking Home will do the right thing. 


My Obedient Home 


/ Devices\/Euents\/ Macro$\ 


Name 


ID 


^ J Sedrfrom Lamp 

|> f Deck Lights 
^ Q Dining Room ChwideBar 


81 

86 

84 

83 


1 jf) Interface Storaqe: f 

Zlo* 


m 


? 5. Your device names are used by PlainTalk . 


Syntax of What You Say to Make it Work 

In order to operate a device using Thinking Home, 
you speak a normal sentence, with the action followed by 
the device name. For example, “Turn off the bedroom 
lamp.” or “Set the thermostat to heat.” The precise syntax 
is shown here in Backus-Naur Form notation: 

<voice - conmiand> : := <action> <device - name) | 

"What is the status of the> <device -name> | 

"Set the" <thermostat -name) "to*’ <mode> 

<action> : "Turn on" | "Turn, off" | "Dim" | 

"Brighten” 

<device-name> : := the device name used in the 
Thinking Home document 

<thermostat-natne> : <device-name> | “thermostat" 

<mode> "Heat" | "Cool" | "Off" 

More examples: 

Turn on the bedroom lamp. 

Turn off the kitchen light. 

Dim the theater lights, — will be dimmed by 35% 

Brighten the bedroom lamp. — For a gentle start in 

the morning. 

Set the thermostat to cool. 

What is the status of the sidewalk lights? 

Note that the thermostat can be referred to by the 
name you gave it, like any other device. Or you can refer 
to it simply as “thermostat” and Thinking Home will use 
the first thermostat it finds in any open document. 

There are some caveats to asking for the status of a 
device. First of all, the Mac will speak the reply and you 
may not be at your Macintosh if you are using the 
wireless mie or mics installed in each room. The other 
issue is the accuracy of the status. This will depend on 
whether the X-10 module is able to report its status. Two- 
way device modules ($25+) will report their status, hut 
the most common modules that sell for $4 to $12 do not. 
If you're using an ActiveHome CM-! 1A computer 
interface, it will keep track of X-10 commands observed 
on your home wiring and will report the status of the 
lamp. This assumes you have not operated it manually. 
The report from a two-way lamp module would reflect its 
actual state, including manual operation. 

You can also control your X-10 thermostat by saying 
“Set the thermostat to cool.” The choices for thermostat 
modes are cool, heat and off. Unfortunately, you cannot 
say “Set the thermostat to 72 degrees.” This is one place 
where PlainTalk is not quite ready. Recognizing spoken 
numbers is much more difficult than most other speech. 

Speakable Items (installed with PlainTalk) is another 
way to access some of Thinking Home’s functionality via 
speech. For example, you may want to know the time of 
sunset on a regular basis. By making a Speakable Item 
like the example below*, you can say to your Macintosh 
“When is sunset?” and the Speakable Items application 
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will run the the AppleScript by that name. The 
AppleScript can, in turn, tell Thinking Home to speak the 
time of today’s sunset as seen here in Figure 6. 



Figure 6. Using Speakahle Items 
to get the time of sunset. 


This is also how you can get XTension v3.0 (from 
Sand Hill Engineering) to respond to your voice. Although 
XTension does not have built-in support for PlainTalk, it 
does have excellent support for AppleScript, You can use 
Speakahle Items for speech recognition and make an 
AppleScript for each command you want recognized. 
Your scripts in the Speakahle Items folder will tell 
XTension which X-10 device to operate. For example, to 
get the time of sunset, you’d write a script almost exactly 
as that for Thinking Home, 


□ UJhen It Sunset? v BB 

T7 ipt ton: 


This AppleScript will speak the time of today's sunset. 
When kept in the Speakahle Items folder, you can make 
it run by asking your Macintosh "When is sunset?” “ 



L*J *HS LLi Gp 

Record "Step" Run Check Syntax 

tell application “XTanslon" 

set today to the current date 

say "Today the sunrise will be at" & today 

end tel 1 

A 

V 

Appl»Sor Ipt | < | mi { 


Figure 7 XTension Speakahle Item 

for getting the time of sunset. 


To use XTension to operate devices via speech, you 
create an AppleScript like that in Figure 8 and name it as 
you intend to speak it. Like before, you name this script 
‘Turn off the bedroom lamp 11 . You'll also need to make a 
similar one for Turn on the bedroom lamp,” 


Turn Off The Bedroom Lamp gfeggfjgs 0 E 


^7 inscription; 


This AppleScript will turn off the Bedroom Lamp. When , 
kept in the Speakahle Items folder, you can make it run by 
ask ing you r Macintosh Turn off the bedroom lamp." ” 


mu m 

ft ward Slop j&m 




ten application “XTension 4 ' 
turnoff "Bedroom Lamp" 
end tell 



Figure 8 * XTension Speakahle Item 
for operation of a device. 


To get device status using XTension, you write an 
AppleScript similar to that shown in Figure 9* 


□ Get Lump Status 

Description; 

108 


This AppleScript will report the statue of the bedroom lamp, 
When kept in the Speakahle Items folder, you can make it 
run by saying your Macintosh "Get lamp status !* 

* 

>■ 



czhu £5 

Rfoofd Run 

Ch #ik Syntax 

tell application "XTension” 

set lampStatus to status "Bedroom Lamp” 
if lampStatus then 

set statusStr to “on, H 
else 

set statusStr to "off*" 
end if 

say The bedroom lamp Is " & statusStr 
end tell 

i 

* 


ApplaScrfct | 4 [mi 

| 

► 



Figure % XTension Speakahle Item 
for getting the status of a device. 


Tips 

Since faster CPU’s seem to perform better than slower 
ones, you will probably want to avoid using a Power 
Macintosh running less than 100 MHz. 

The Shure web site has a wealth of useful information 
and general advice regarding the various options, such as 
ceiling - vs. wall-mounted microphones. 
<http;//www, shure, com/support/technotes/app- 
soundcard.html#Macintosh> 
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Before you deino your cool home to others, test it out 
in advance. In particular, check that it works reliably from 
all locations you plan to he when showing it. When using 
a wireless microphone, ensure the range is sufficient to 
operate consistently from all locations where you will be 
using it. Also, make sure the ambient sounds are the 
same. Putting on background music just as your guests 
arrive will change the "noise 1 ' level and your speech 
commands may very well get lost. Once you have it set 
up nicely, your friends will be amazed. 

Conclusion 

Integrating speech recognition into your Macintosh X- 
10 home automation can be useful, convenient and fun. 
This futuristic technoiogy is ready and affordable today 
and still improving. Select an arrangement that fits your 
lifestyle and budget and try it out. 


Links 

* http://www.apple.com/macos/speech/ 

Apple's Plaimalk download page. 

* http;//www.shedxom/ 

Sand Hill Engineering home page (for XTension) 

* http://www.alwaysthinking.com/products/products.html 

Thinking Home product page. 

* http://wwwJotusproductions.com 

Lotus Productions (wireless microphones) 

* http://www.shure.coTn/support/technotes/3pp- 
soundcard,htm!#Madntosh 

Shu re home page (audio mixers) 

* news:comp.home.automation 

Home automation newsgroup with emphasis on X-1CX 
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AppMalcer 12 


i«(%ni^<.r^smpi®yst*. *v§ 

PO Box 5200 Westlake Village, CA • 91359-5200 • Voice: 800/MACDEV-l (800/622-3381) 
Outside US/Canada: 805/494-9797 • Fax: 805/494-9798 • E-mail: orders@devdepot.com 


Just point and click, 
drag and drop and 
AppMaker builds your programs 
interface. One click can the gen¬ 
erate the source code in C, C++, 
Java, for Tools Plus Pro, or for 
PowerPlant! 


Developer Depot, the home of 
hundreds of tools for software 
development, web develop¬ 
ment, network administration, 
and other tools and toys for 
techies! Visit our new 
Getting Started store for 
everything you need to start 
developing on the Mac! 


Future BASIC 3 

$159 

The easiest and most 
flexible way to develop 
applications on the Mac! A the pro¬ 
gram builder let's you create your 
application with drag and drop tools. 
The only BASIC development system 
that let's you have 100% access to all 
the power of the Mac Toolbox! 


Discover Programming 
for Macintosh 

$44.95 

The easiest way to learn how to 
build C/C++ and Java applica¬ 
tions! Contains the award 
ning CodeWarrior Development 
system, example source code, 
and "how-to" books on CD ROM! 
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SuSE. 

# 

{soo' sah} is (soo' purb} 


HOW DO YOu SAY 

Superb 

IN 

LINuX? 


When you think of Superb, you think of unusually high quality. Like a superb wine, for example. Majestic. 
Rich, Luxurious. Superior. ■ SuSE Linux is all that. And more. More experience. More adaptability. More 
applications—over 1500. ■ More power to you. And more freedom, too. m No wonder more than 50,000 
enterprises worldwide bank on its superb open source solutions. Making SuSE the international Linux leader^ 
setting a higher standard for excellence, simplicity and support, 
say superb in Linux? SuSE. It's a lesson well learned. 


Versions for Intel, Alpha, and PowerPC 

© 2000 SuSE. All ngMa reserved. SuSE, and SuSE logo are trademarks of SuSE GmbH. Other names may be trademarks of their respective owners, 


Even the price is superb. ■ So, how do you 

www.SuSE.com 


The freedom to change. 
The power to change the Linux world. 

SuSE 
















M ac developers depended on CodeWarrior to make the 
platform architecture shift from 68K to PowerPC 
processors. Now CodeWarrior does it again, speeding your 
transition to the next new operating system. CodeWarrior for 
Mac OS, Version 6.0 supports development for both OS X 


and Classic Mac operating systems from a single, powerful, 
award-winning Integrated Development Environment. 
Discover how CodeWarrior for Mac OS, Version 6.0 can 
help you realize your Mac development dreams. 

Visit www.metrowerks.com/go/mac. 


CodeWarrior 




metrowerks’ 


Software Starts Hare 


i _ 


































